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

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

Примечание.

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]

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

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

Запрос

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": { … },
    …
}

Примечание.

Отклик

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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