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

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

  • Статья

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

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

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

  1. Обновите манифест приложения Teams.
  2. Обновление разрешений Microsoft Graph.
  3. Обработка уведомлений веб-перехватчика Microsoft Graph.
  4. Create или удалите подключения 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.11/MicrosoftTeams.schema.json",
  "manifestVersion": "1.11",
  ...
  "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

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

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

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

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

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

Пример полезных данных для уведомления веб-перехватчика Microsoft Graph

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

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

  • Вы можете игнорировать 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, он пытается опубликовать уведомление об изменении несколько раз в течение четырех часов. После этого уведомление об изменении удаляется и не доставляется.

Примечание.

202 - Accepted Отправьте код состояния, как только вы получите уведомление об изменении, даже до проверки его подлинности. Вы подтверждаете получение уведомления об изменениях и предотвращаете ненужные повторные попытки. Текущее значение времени ожидания — 30 секунд, но это время может быть сокращено в будущем для оптимизации производительности службы. Если URL-адрес уведомления не отвечает в течение 30 секунд на более чем 10 % запросов из Microsoft Graph в течение 10 минут, все последующие уведомления будут отложены и повторятся в течение 4 часов. Если URL-адрес уведомления не отвечает в течение 30 секунд на более чем 20 % запросов из Microsoft Graph в течение 10 минут, все последующие уведомления будут удалены.

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

  • Убедитесь, что срок действия маркера не истек.
  • Убедитесь, что маркер не был изменен и был выдан платформа удостоверений Майкрософт.
  • Убедитесь, что утверждение appId в validationToken имеет значение 0bf30f3b-4a52-48df-9a82-234910c4a086.
  • Убедитесь, что утверждение 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]

Create или удаление подключений 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 см. в статье Create, обновление и удаление элементов, добавленных приложением с помощью соединителей Microsoft Graph.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры запросов

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

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

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

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

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