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

  • Статья

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

Установка

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

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

Рекомендуемая конфигурация:

  • Windows 10, Windows Server 2016 R2 и выше
  • .NET Framework 4.7.2
  • .NET Core Desktop Runtime 7.0 (x64)
  • 8 ядер, 3 ГГц
  • 16 ГБ ОЗУ, 2 ГБ места на диске
  • Сетевой доступ к источнику данных и Интернету через 443

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

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

Примечание.

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

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

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

Get-ExecutionPolicy -List

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

Обновление

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

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

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

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

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

  2. Установщик предложит установить среду выполнения .NET 7 desktop, если она еще не установлена.

  3. Разрешить обмен данными с конечной точкой *.office.com.

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

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

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

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

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

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

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

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

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

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

  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
$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 в состоянии выполнения (ниже снимок экрана в Windows 11). Если нет, щелкните правой кнопкой мыши и запустите службу.

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

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

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

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

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

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

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

  2. Проверьте, доступна ли gcs.office.com домена. Выполните следующие действия.

    • В 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

    Ответ должен содержать выходные данные "TcpTestSucceeded: 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 в состоянии выполнения (ниже снимок экрана в Windows 11). Если нет, щелкните правой кнопкой мыши и запустите службу. Снимок экрана: службы в диспетчере задач 2.
  2. Если проблема по-прежнему возникает, обратитесь в службу поддержки, отправив электронное письмо по адресу MicrosoftGraphConnectorsFeedback@service.microsoft.comи предоставьте два последних файла журнала. Вручную перейдите к расположению ниже, чтобы получить доступ к журналам и поделиться ими с командой. C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

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

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