Поделиться через

Агент соединителя Microsoft Graph

  • Статья

Для использования локальных соединителей необходимо установить программное обеспечение агента соединителя Microsoft Graph . Это обеспечивает безопасную передачу данных между локальными данными и API соединителя. В этой статье описано, как установить и настроить агент.

Установка

Скачайте последнюю версию агента соединителя Microsoft Graph и установите программное обеспечение с помощью помощника по настройке установки. Заметки о выпуске программного обеспечения агента соединителя доступны здесь.

Проверка политики выполнения

Необходимо задать политику выполнения, чтобы разрешить выполнение удаленных подписанных скриптов. Если какой-либо компьютер или политика группового уровня ограничивает одно и то же, установка GCA завершается ошибкой. Выполните следующую команду, чтобы получить политику выполнения:

Get-ExecutionPolicy -List

Дополнительные сведения и настройку правильной политики выполнения см. в статье Политика выполнения.

Используя рекомендуемую конфигурацию компьютера, экземпляр агента соединителя может обрабатывать до трех подключений. Любые подключения за пределами этого могут снизить производительность всех подключений в агенте. Ниже приведена рекомендуемая конфигурация.

Если прокси-серверы или брандмауэры вашей организации блокируют обмен данными с неизвестными доменами, добавьте следующие правила в список разрешенных.

M365 Корпоративный M365 GCC M365 GCCH
1. *.servicebus.windows.net 1. *.servicebus.usgovcloudapi.net 1. *.servicebus.usgovcloudapi.net
2. *.events.data.microsoft.com 2. *.events.data.microsoft.com 2. *.events.data.microsoft.com
3. *.office.com 3. *.office.com 3. *.office.com, *.office365.us
4. https://login.microsoftonline.com 4. https://login.microsoftonline.com 4. https://login.microsoftonline.com, https://login.microsoftonline.us
5. https://gcs.office.com/ 5. https://gcsgcc.office.com 5. https://gcs.office365.us/
6. https://graph.microsoft.com/ 6. https://graph.microsoft.com 6. https://graph.microsoft.com/, https://graph.microsoft.us/

Примечание.

Проверка подлинности прокси-сервера не поддерживается. Если в вашей среде есть прокси-сервер, требующий проверки подлинности, рекомендуется разрешить агенту соединителя обходить прокси-сервер.

Обновление

Агент соединителя Graph можно обновить двумя способами:

  1. Скачивание и установка агента соединителя Graph вручную по ссылке, предоставленной в разделе установки.

  2. Нажатие кнопки "Обновить", доступной в области подключения, как показано на рисунке: пример моментального снимка обновления GCA одним щелчком из области подключения.

Кнопка обновления недоступна для агентов, выполняющих обновление с версии 1.x до версии 2.x. Если агент обновляется с версии 1.x до версии 2.x, выполните следующие действия:

  1. Скачайте установщик по ссылке, предоставленной в разделе установки.

  2. Установщик запрашивает установку классической среды выполнения .NET 8, если она еще не установлена.

  3. Разрешить связь с конечной точкой *.office.com.

  4. После установки приложение конфигурации GCA перезапускается. Если GCA не зарегистрирована, войдите и продолжите регистрацию.

  5. Если GCA уже зарегистрирована, приложение конфигурации GCA отображает следующее сообщение об успешном выполнении: Пример моментального снимка успешной проверки работоспособности на странице входа GCA.

  6. Если вы заметили какие-либо ошибки, выполните предложенные действия по устранению неполадок в сообщении об ошибке и закройте & снова откройте приложение конфигурации GCA.

  7. Если в сообщении об ошибке сказано: "Не удается определить работоспособность агента. Если ошибка не исчезнет, обратитесь в службу поддержки.", перезапустите GcaHostService (шаги, описанные в разделе об устранении неполадок) и снова откройте приложение конфигурации GCA.

  8. Проверки можно выполнить в любое время, закрыв и открыв приложение GCA Config или нажав кнопку "Проверка работоспособности" рядом с кнопкой "Изменить" на экране сведений о регистрации. Пример моментального снимка успешной проверки работоспособности на странице регистрации GCA.

Создание и настройка приложения для агента

Во-первых, войдите и обратите внимание, что минимальные необходимые привилегии для учетной записи — это администратор поиска. Затем агент запросит указать сведения о проверке подлинности. Выполните действия, чтобы создать приложение и создать необходимые сведения о проверке подлинности.

Создать приложение

  1. Перейдите на портал Azure и войдите с учетными данными администратора для клиента.

  2. Перейдите в раздел Microsoft Entra ID ->Регистрация приложений в области навигации и выберите Создать регистрацию.

  3. Укажите имя приложения и выберите Зарегистрировать.

  4. Запишите идентификатор приложения (клиента).

  5. Откройте разрешения API в области навигации и выберите Добавить разрешение.

  6. Выберите Microsoft Graph , а затем — Разрешения приложения.

  7. Найдите следующие разрешения и выберите Добавить разрешения.

    Разрешение Когда требуется разрешение
    ExternalItem.ReadWrite.OwnedBy или ExternalItem.ReadWrite.All Всегда
    ExternalConnection.ReadWrite.OwnedBy Всегда
    Directory.Read.All Требуется для общей папки, соединителей MS SQL и Oracle SQL

  8. Выберите Предоставить согласие администратора для [Имя_клиента] и подтвердите, нажав Кнопку Да.

  9. Убедитесь, что разрешения находятся в состоянии "предоставлено".

    Разрешения, предоставленные зеленым цветом в правом столбце.

Настройка проверки подлинности

Сведения о проверке подлинности можно указать с помощью секрета клиента или сертификата. Следуйте инструкциям по своему усмотрению.

Настройка секрета клиента для проверки подлинности

  1. Перейдите на портал Azure и войдите с учетными данными администратора для клиента.

  2. Откройте "Регистрация приложения " в области навигации и перейдите к соответствующему приложению. В разделе Управление выберите Сертификаты и секреты.

  3. Выберите Новый секрет клиента и выберите срок действия секрета. Скопируйте созданный секрет и сохраните его, так как он не отображается снова.

  4. Используйте этот секрет клиента и идентификатор приложения для настройки агента. Принимаются буквенно-цифровые символы. Пустые пробелы нельзя использовать в поле Имя агента.

Использование сертификата для проверки подлинности

Существует три простых шага для использования проверки подлинности на основе сертификата.

  1. Создание или получение сертификата
  2. Отправка сертификата на портал Azure
  3. Назначение сертификата агенту
Шаг 1. Получение сертификата

Скрипт можно использовать для создания самозаверяющего сертификата. Ваша организация может не разрешать самозаверяемые сертификаты. В этом случае используйте эти сведения, чтобы понять требования и получить сертификат в соответствии с политиками вашей организации.

$dnsName = "<TenantDomain like agent.onmicrosoft.com>" # Your DNS name
$password = "<password>" # Certificate password
$folderPath = "D:\New folder\" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "agentcert" # What do you want to call the cert files? without the file extension
$yearsValid = 10 # Number of years until you need to renew the certificate
$certStoreLocation = "cert:\LocalMachine\My"
$expirationDate = (Get-Date).AddYears($yearsValid)
$certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword
Шаг 2. Отправка сертификата на портал Azure

  1. Откройте приложение и перейдите к разделу сертификаты и секреты в левой области.

  2. Выберите Отправить сертификат и отправьте файл .cer.

  3. Откройте Регистрация приложений и выберите Сертификаты и секреты в области навигации. Скопируйте отпечаток сертификата.

Список сертификатов отпечатков при выборе сертификатов и секретов в области слева.

Шаг 3. Назначение сертификата агенту

Использование примера скрипта для создания сертификата позволит сохранить PFX-файл в расположении, заданном в скрипте.

  1. Скачайте PFX-файл сертификата на компьютер агента.

  2. Дважды щелкните PFX-файл, чтобы открыть диалоговое окно установки сертификата.

  3. Выберите Локальный компьютер для расположения хранилища при установке сертификата.

  4. После установки сертификата откройте управление сертификатами компьютера в меню Пуск .

  5. Выберите только что установленный сертификат в разделе Личные>сертификаты.

  6. Выберите и удерживайте (или щелкните правой кнопкой мыши) сертификат и выберите Параметр Все задачи>Управление закрытыми ключами .

  7. В диалоговом окне разрешения выберите добавить параметр. Откроется новое окно. Выберите в нем параметр "Расположения". Выберите компьютер, на котором установлен агент, в списке показанных расположений, и нажмите кнопку ОК.

  8. В диалоговом окне выбора пользователя напишите: NT Service\GcaHostService и нажмите кнопку ОК. Не нажимайте кнопку Проверить имена .

  9. Нажмите кнопку ОК в диалоговом окне разрешений. Теперь на компьютере агента настроено создание маркеров с помощью сертификата.

Устранение неполадок

Сбой установки

Если произошел сбой установки, проверьте журналы установки, выполнив команду msiexec /i "< путь к msi >\GcaInstaller.msi" /L*V "< конечный путь >\install.log". Убедитесь, что вы не получаете никаких исключений безопасности. Как правило, эти исключения возникают из-за неправильных параметров политики. Политика выполнения должна быть удаленно подписана. Дополнительные сведения см. в разделе "Установка" этого документа.

Если ошибки не удается устранить, отправьте сообщение электронной почты в службу поддержки через MicrosoftGraphConnectorsFeedback@service.microsoft.com журналы.

Сбой регистрации

Если вход для настройки приложения завершается сбоем и отображает ошибку "Сбой входа, нажмите кнопку входа, чтобы повторить попытку", даже после успешной проверки подлинности браузера, откройте services.msc и проверьте, запущена ли GcaHostService. Если он не запускается, запустите его вручную. В диспетчере задач перейдите на вкладку Службы и проверьте, находится ли GcaHostService в состоянии выполнения. Если нет, щелкните правой кнопкой мыши и запустите службу.

Снимок экрана: службы в диспетчере задач.

Если служба не запускается с ошибкой "Служба не запущена из-за сбоя входа", проверьте, имеет ли виртуальная учетная запись NT Service\GcaHostService разрешение на вход в качестве службы на компьютере. Инструкции см. по этой ссылке . Если параметр добавления пользователя или группы неактивен в разделе Локальные политики\Назначение прав пользователя, это означает, что пользователь, пытающийся добавить эту учетную запись, не имеет прав администратора на этом компьютере или имеет групповую политику, переопределяющую ее. Групповую политику необходимо обновить, чтобы разрешить службе узла входить в систему как услуга.

Сбой после регистрации

После регистрации некоторые локальные параметры могут повлиять на подключение агента.

Агент находится в автономном режиме

Агент считается автономным, если ему не удается связаться со службами соединителя графа. В таких случаях выполните следующие действия.

  1. Проверьте, запущен ли агент. Войдите на компьютер, на котором установлен агент, и проверьте, запущен ли он. В диспетчере задач перейдите на вкладку Службы и проверьте, находится ли GcaHostService в состоянии выполнения. Если нет, щелкните правой кнопкой мыши и запустите службу.

    Снимок экрана: службы в диспетчере задач.

  2. Проверьте, доступна ли gcs.office.com домена. (Для клиента GCC замените gcsgcc.office.com, а для клиента GCCHigh замените gcs.office365.us, как показано в начальной таблице.) Выполните следующие действия.

    • В PowerShell выполните следующую команду:
    tnc gcs.office.com -Port 443

    Ответ должен содержать выходные данные TcpTestSucceeded: True, как показано ниже:

    Снимок экрана: tnc.

    Если значение равно false, убедитесь, что домен разрешен в прокси-сервере или брандмауэре, а запросы проходят через прокси-сервер.

    • Для более конкретного теста или если не удается выполнить tnc из-за блокировки связи ICMP в сети, выполните следующую команду:
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

    Выходные данные должны содержать "StatusCode: 200".

    Снимок экрана: wget 200.

    Если значение не равно 200, убедитесь, что домен разрешен в прокси-сервере или брандмауэре, а запросы проходят через прокси-сервер.

  3. Если шаги успешно пройдены и агент по-прежнему находится в автономном режиме, проверьте журналы GCA на наличие проблем с прокси-сервером сети.

    • Журналы GcaHostService можно найти в заданном расположении (возможно, потребуется вручную перейти по этому пути — копирование вставки в проводнике может не работать):
      1. Для ОС Windows Server 2016: C:\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Для всех остальных поддерживаемых версий ОС Windows: C:\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Отсортируйте файлы журнала в папке в обратном порядке "Время изменения" и откройте последние два файла.
    • Проверьте наличие сообщений об ошибках со следующим текстом: "Не удалось установить подключение, так как целевой компьютер отказался от него".
      1. Это означает, что возникла проблема с параметрами сети, которая не позволяет виртуальной учетной записи GcaHostService связаться с конечной https://gcs.office.com точкой.
      2. Обратитесь к группе сети или прокси-сервера, чтобы разрешить виртуальной учетной записи (NT Service\GcaHostService) отправлять трафик в этот домен.
      3. Вы можете убедиться, что проблема устранена, если файл журнала больше не содержит этих ошибок.

  4. Если ни один из шагов не устраняет проблему, обратитесь в службу поддержки, отправив электронное письмо по адресу MicrosoftGraphConnectorsFeedback@service.microsoft.comи предоставьте два последних файла журнала из указанного выше расположения.

Агент недоступен

При настройке подключения, если агент недоступен, отображается следующий экран:

Снимок экрана: недоступность агента

Используя пространство имен служебной шины, предоставленное в сведениях об ошибке, выполните следующие действия для устранения неполадок:

  1. В PowerShell выполните следующую команду:

    tnc <yournamespacename>.servicebus.windows.net -port 443

    Ответ должен содержать выходные данные TcpTestSucceededed: True:

    Снимок экрана: tnc 2.

    Если значение равно false, убедитесь, что домен разрешен в прокси-сервере или брандмауэре, а запросы проходят через прокси-сервер.

  2. Если не удается запустить tnc из-за блокировки связи ICMP в сети, выполните следующую команду в PowerShell:

    wget https://<yournamespacename>.servicebus.windows.net/

    Выходные данные должны содержать "StatusCode: 200":

    Снимок экрана: wget 2.

    Если значение равно false, убедитесь, что домен разрешен в прокси-сервере или брандмауэре, а запросы проходят через прокси-сервер.

  3. Если ни один из шагов не устраняет проблему, обратитесь в службу поддержки, отправив электронное письмо по адресу MicrosoftGraphConnectorsFeedback@service.microsoft.comи предоставьте два последних файла журнала из указанного выше расположения.

Выполняется обновление

Эта ошибка появляется, когда уже выполняется обновление, и ошибка должна уйти не более чем через 30 минут.

Снимок экрана: обновление выполняется.

Если ошибка сохраняется через 30 минут, выполните следующие действия.

  1. Проверьте, запущен ли агент. Войдите на компьютер, на котором установлен агент, и проверьте, запущен ли он. В диспетчере задач перейдите на вкладку Службы и проверьте, находится ли GcaHostService в состоянии выполнения. Если нет, щелкните правой кнопкой мыши и запустите службу. Снимок экрана: службы в диспетчере задач 2.

  2. Если проблема по-прежнему возникает, обратитесь в службу поддержки, отправив электронное письмо по адресу MicrosoftGraphConnectorsFeedback@service.microsoft.comи предоставьте два последних файла журнала. Вручную перейдите к расположению для доступа к журналам и предоставления общего доступа к ним команде : C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Сбой подключения

Если действие "Проверить подключение" завершается ошибкой при создании подключения и отображает ошибку "Проверьте имя пользователя или пароль и путь к источнику данных", даже если указанные имя пользователя и пароль указаны правильно, убедитесь, что учетная запись пользователя имеет интерактивные права на вход на компьютер, на котором установлен агент соединителя. Чтобы проверить права входа, ознакомьтесь с документацией по управлению политикой входа . Кроме того, убедитесь, что источник данных и компьютер агента находятся в одной сети.