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

Включение упрощенного интерфейса администрирования для соединителя Microsoft Graph

  • Статья

В этой статье описывается, как включить упрощенный интерфейс администрирования для соединителя Microsoft Graph в Центре администрирования Teams. При включении этого интерфейса администраторы Teams смогут легко включить или отключить настраиваемый соединитель Microsoft Graph в Центре администрирования Teams.

Упрощенный интерфейс администрирования в Центре администрирования Teams

Чтобы включить упрощенный интерфейс администрирования в Центре администрирования Teams, выполните следующие действия.

  1. Обновите манифест приложения Teams.
  2. Обновление разрешений Microsoft Graph.
  3. Обработка уведомлений веб-перехватчика Microsoft Graph.
  4. Создание или удаление подключений Microsoft Graph.
  5. Проверьте интерфейс, включив соединитель Microsoft Graph в Центре администрирования Teams.

Обновление манифеста приложения Teams

В манифесте приложения Teams в корневом каталоге на том же уровне, что и свойства, такие как имя, описание и значки, добавьте свойство graphConnector (появилось в версии 1.11 манифеста приложения) с notificationUrl. Это поле содержит URL-адрес, по которому отправляются уведомления соединителя Microsoft Graph для приложения. Версия манифеста приложения должна быть версии 1.13 или более поздней, чтобы упростить работу администратора.

Убедитесь, что в манифест добавлено свойство webApplicationInfo . После обновления манифеста отправьте его, загрузив неопубликованное приложение или опубликовав приложение в Магазине.

{
 "$schema":"https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
  "manifestVersion": "1.13",
  ...
  "webApplicationInfo": {
    "id": "<AAD_APP_ID>",  // e.g. "7e47846e-4bef-4c42-9817-a14e92287f28"
    "resource": "<AAD_APP_RESOURCE>" // e.g. "api://xmngc.loca.lt/7e47846e-4bef-4c42-9817-a14e92287f28"

  },
  "graphConnector": {
    "notificationUrl": "<AAD_APP_NOTIFICATION_URL>"
  }
}

Обновление разрешений Microsoft Graph

  1. Перейдите к Центр администрирования Microsoft Entra.
  2. Разверните меню Удостоверение и выберите Приложения>Регистрация приложений.
  3. Выберите регистрацию приложения.
  4. Перейдите к разделу Разрешения> APIДобавление разрешения>Microsoft Graph.
  5. ExternalConnection.ReadWrite.OwnedBy Выберите разрешения и ExternalItem.ReadWrite.OwnedBy Microsoft Graph, как показано в следующем примере.

Обновленные разрешения Microsoft Graph

Обработка уведомлений веб-перехватчика Microsoft Graph

Когда администратор включает иливыключает соединитель Microsoft Graph из Центра администрирования Teams, Microsoft Graph отправляет уведомление об изменении по URL-адресу, указанному в свойстве notificationUrl манифеста. Ваше приложение должно соответствующим образом управлять этими подключениями Microsoft Graph.

Уведомления об изменениях

Дополнительные сведения о настройке уведомлений об изменениях см. в статье Настройка уведомлений об изменениях в данных ресурсов. В следующем примере показаны полезные данные:

{
  "validationTokens": [
    "[jwt validation token]"
  ],
  "value": [
    {
      "changeType": "updated",
      "clientState": null,
      "resource": "external",
      "resourceData": {
        "@odata.id": "external",
        "id": "[graph connector id]",
        "state": "enabled", // or disabled
        "connectorsTicket": "[An opaque encoded string]",
        "@odata.type": "#Microsoft.Graph.connector"
      },
      "subscriptionExpirationDateTime": "2024-08-30T13:01:48.3441108-07:00",
      "subscriptionId": "[change notification's subscription id]",
      "tenantId": "[customer's tenant id]"
    }
  ]
}

Сведения о том, как проверить уведомление о входящих изменениях, см. в статье Проверка подлинности уведомлений.

Примите во внимание следующее.

  • Вы можете игнорировать subscriptionExpirationDateTime и subscriptionId.
  • Уведомление об изменении предназначено для управления соединителем Microsoft Graph только в том случае, если тип @odata.type данных ресурса соответствует типу в примере полезных данных.
  • Идентификатор клиента — это идентификатор клиента. При вызове microsoft API Graph для управления подключениями Microsoft Graph необходимо создать маркер приложения от имени идентификатора клиента.
  • Вы можете вызвать API Graph Майкрософт, чтобы получить отображаемое имя клиента и доменное имя по умолчанию. Эти сведения помогут сопоставить идентификатор клиента с уникальным идентификатором в системе. Дополнительные сведения см. в статье Поиск сведений о клиенте по идентификатору клиента.
  • В resourceData используйте состояние , чтобы определить, следует ли создавать или удалять подключения. Для создания подключений требуется connectorsTicket .

Обработка уведомления о включении соединителя

Чтобы обработать уведомления о включении соединителя, выполните следующее:

  • Определите, какие подключения Microsoft Graph следует создать (сколько подключений и какая схема для каждого подключения), используя API списка внешних подключений для запроса всех подключений. Определите, следует ли создавать все подключения с нуля, возобновлять создание соединений (в потоке устойчивости) или нет операции (если все необходимые подключения уже находятся в состоянии готовности ).
  • Соединение создается в состоянии черновика. Передайте непрозрачную connectorsTicket строку в API создания подключения в заголовке GraphConnectors-Ticket HTTP.
  • Зарегистрируйте схему.
  • После успешного создания или обновления схемы подключение должно достичь состояния готовности .

Обработка уведомления об отключении соединителя

Обработка уведомлений об отключении соединителя:

  • Определите, какие подключения Microsoft Graph следует удалить, используя API списка внешних подключений для запроса всех подключений.
  • Удалите все подключения с помощью API удаления внешнего подключения.
  • Мы рекомендуем создать логику устойчивости, чтобы повторить попытку удаленного подключения, чтобы убедиться, что оно удалено.

Запрос

POST https://example.com/notificationEndpoint
Content-type: application/json
Content-length: 100

{
  "value": [
    {
      "changeType": "updated",
      "subscriptionId": "79f3b611-7f15-4bdd-9422-9606a24e49f3",
      "resource": "external",
      "clientState": null,
      "resourceData": {
        "@odata.type": "#Microsoft.Graph.connector",
        "@odata.id": "external",
        "id": "{{connectorId}}",
        "state": "enabled" //e.g. enabled or disabled
        "connectorsTicket":"eyJhbGciOiJIUzI1…"
      },
      "subscriptionExpirationDateTime": "2021-06-26T12:40:26.4436785-07:00",
      "tenantId": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93"
    }
  ],
  "validationTokens": [ "eyJ0eXAiOiJKV…" ]
}

Отклик

HTTP/1.1 202 Accepted
Content-type: application/json
Content-length: 0

Необходимо отправить 202 - Accepted код состояния в ответе в Microsoft Graph. Если Microsoft Graph не получает код класса 2xx, он пытается опубликовать уведомление об изменениях несколько раз в течение четырех часов. После этого уведомление об изменении удаляется и не доставляется.

Чтобы проверить подлинность validatonToken, выполните следующие действия:

  • Убедитесь, что срок действия маркера не истек.
  • Убедитесь, что маркер не был изменен и был выдан платформа удостоверений Майкрософт.
  • Убедитесь, что утверждение appId в validationToken.
  • Убедитесь, что утверждение aud в validationToken совпадает с указанным вами утверждением "{Teams-appid}}".

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

В следующем примере показан маркер проверки.

{ "typ": "JWT", "alg": "RS256", "x5t": "nOo3ZDrODXEK1jKWhXslHR_KXEg", "kid": "nOo3ZDrODXEK1jKWhXslHR_KXEg" }.{ "aud": "e478830d-8f49-4c26-80c6-58f68e0f064b", "iss": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "iat": 1624649764, "nbf": 1624649764, "exp": 1624736464, "aio": "E2ZgYGjnuFglnX7mtjJzwR5lYaWvAA==", "appid": "0bf30f3b-4a52-48df-9a82-234910c4a086", "appidacr": "2", "idp": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "oid": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "rh": "0.AX0AtrpOnw1SwEmFzHslx41KkzsP8wtSSt9ImoIjSRDEoIZ9AAA.", "sub": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "tid": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93", "uti": "mIB4QKCeZE6hK71XUHJ3AA", "ver": "1.0" }.[Signature]

Создание или удаление подключений Microsoft Graph

При создании подключения к приложению Teams необходимо отправить соединителиTickets из полезных данных, полученных в качестве GraphConnectors-Ticket заголовка. В следующем примере показан этот процесс.

Запрос

POST https://graph.microsoft.com/v1.0/external/connection
GraphConnectors-Ticket: {{connectorsTicket}}
Content-type: application/json
Authorization: bearer {{accessToken}}

{
    "id": "{{connectionId}}",
    "name": "Contoso HR",
    "description": "Connection to index Contoso HR system",
    "connectorId": "{{connectorId}}",
    "enabledContentExperiences": "MicrosoftSearch, Compliance, …",
    "searchSettings": { … },
    "complianceSettings": { … },
    …
}

Примечание.

  • При создании подключения для {{connectorId}} необходимо задать значение, указанное в уведомлении от соединителей Graph.
  • Вы должны получить {{accessToken}} из платформа удостоверений Майкрософт для клиента, который уведомляется.

Отклик

HTTP/1.1 200 Accepted
Content-type: application/json
Content-length: 0

Примечание.

Для созданных подключений можно включить различные возможности Microsoft 365. Дополнительные сведения см. в обзоре соединителей Microsoft Graph .

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

Проверьте работу, включив соединитель Microsoft Graph в Центре администрирования Teams.

Чтобы проверить взаимодействие, выполните следующие действия.

  1. Войдите в Центр администрирования Teams в качестве администратора Teams или глобального администратора клиента.
  2. Выберите колонку Управление приложениями на левой панели.
  3. Перейдите к приложению Teams.
  4. На странице сведений о приложении Teams вы увидите новую вкладку Соединитель Graph , которая позволяет администратору включать или отключать соединитель Microsoft Graph.
  5. Нажмите кнопку переключателя, чтобы отправлять уведомления о включении или отключении в конечную точку уведомлений приложения, как указано в свойстве graphConnector.notificationUrl в манифесте приложения.

Сделать соединитель Microsoft Graph доступным для других организаций в Центре администрирования Teams

Вы можете отправить соединитель Microsoft Graph, упакованный в виде приложения Teams, расширенного в Microsoft 365, в Центр партнеров Майкрософт. Это позволяет корпорации Майкрософт проверить соединитель Microsoft Graph, чтобы другие организации могли обнаружить и развернуть его в Центре администрирования Microsoft Teams.

Вы можете использовать пошаговое руководство по отправке , чтобы узнать, как отправить приложение. Убедитесь, что вы отправляете приложение Teams на вкладке Microsoft 365 и Copilot в предложениях Marketplace.

Необходимо отправить PDF-файл на шаге Дополнительные сведения о сертификации . Корпорация Майкрософт использует сведения, которые вы предоставляете в этом PDF-файле, чтобы убедиться, что соединитель Microsoft Graph работает должным образом в Microsoft 365 Copilot. Pdf-файл должен содержать следующие разделы:

  • Тестовые учетные записи, лицензионные ключи и учетные данные
  • Пользовательское имя по вертикали
  • Семантические метки
  • Пример Запросы
  • Описание подключения
  • Параметры действий

Тестовые учетные записи, лицензионные ключи и учетные данные

Создайте учетную запись пользователя в демонстрационном клиенте, которую корпорация Майкрософт может использовать для проверки соединителя Microsoft Graph. Это можно сделать в разделе Пользователи Центра Microsoft 365 Admin. Убедитесь, что эта новая учетная запись пользователя имеет лицензию на Microsoft 365 Copilot.

В этом разделе PDF-файла укажите учетные данные и все применимые лицензионные ключи для этой новой учетной записи пользователя. Эти сведения являются обязательными. Дополнительные сведения о подготовке учетной записи пользователя к проверке см. в статье Рекомендации по предоставлению заметок о тестировании.

После проверки приложения корпорацией Майкрософт можно отозвать доступ к учетной записи пользователя.

Пользовательское имя по вертикали

Создайте настраиваемую вертикальную вертикальную линию, которая возвращает только результаты из пользовательского соединителя Microsoft Graph. Это можно сделать в разделе Вертикали вкладки Настройка на портале поиска & аналитики. В этом разделе PDF-файла укажите имя настраиваемой вертикали. Имя настраиваемой вертикали является обязательным.

Семантические метки

В разделе Семантические метки укажите, какие свойства схемы подключения имеют семантические titleметки , urlи iconUrl . Это сопоставление схемы является обязательным.

Пример Запросы

В разделе Пример Запросы укажите два примера запросов, которые корпорация Майкрософт может использовать для проверки соединителя Microsoft Graph в Microsoft 365 Copilot. Эти запросы должны включать по крайней мере частичное совпадение с семантической title меткой. Эти запросы являются обязательными.

Описание подключения

В разделе Описание подключения укажите description свойство для настраиваемого подключения Microsoft Graph. Корпорация Майкрософт использует это, чтобы убедиться, что подключение Microsoft Graph содержит подробное описание Microsoft 365 Copilot. Описание не является обязательным.

Параметры действий

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