为 Microsoft Graph 连接器启用简化的管理体验

项目
11/07/2024

本文介绍如何在 Teams 管理中心为 Microsoft Graph 连接器启用简化的管理体验。启用此体验后，Teams 管理员可以在 Teams 管理中心无缝启用或禁用自定义 Microsoft Graph 连接器。

简化 Teams 管理中心中的管理体验

若要在 Teams 管理中心启用简化的管理体验，请执行以下操作：

更新 Teams 应用清单。
更新 Microsoft Graph 权限。
处理Microsoft Graph Webhook 通知。
创建或删除Microsoft Graph 连接。
通过在 Teams 管理中心启用 Microsoft Graph 连接器来验证体验。

更新 Teams 应用清单

在 Teams 应用清单的根目录中，在与名称、说明和图标等属性相同的级别上，使用 notificationUrl 添加应用清单 v1.11 中引入的 graphConnector 属性 () 。此字段包含应用程序Microsoft Graph 连接器通知发送到的 URL。应用清单版本必须为 v1.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 权限

转到Microsoft Entra 管理中心。
展开“标识”菜单，转到“应用程序>应用注册”。
选择应用注册。
转到 API 权限>Microsoft Graph添加权限>。
ExternalConnection.ReadWrite.OwnedBy选择和 ExternalItem.ReadWrite.OwnedBy Microsoft Graph 权限，如以下示例所示。

更新了 Microsoft Graph 权限

处理 Microsoft Graph Webhook 通知

当管理员从 Teams 管理中心打开或关闭 Microsoft Graph 连接器时，Microsoft Graph 会将更改通知发送到清单中的 notificationUrl 属性中指定的 URL。你的应用需要相应地管理这些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。
仅当资源数据的 @odata.type 与示例有效负载中的@odata类型匹配时，更改通知才适用于 Microsoft Graph 连接器管理。
标识的 tenantId 是客户的租户 ID。调用 Microsoft 图形 API 以管理 Microsoft Graph 连接时，必须代表此客户的租户 ID 生成应用令牌。
可以调用Microsoft 图形 API来获取客户的显示名称和默认域名。此信息有助于将 tenantId 映射到系统中的唯一标识符。若要了解详细信息，请参阅按租户 ID 查找租户信息。
在 resourceData 中，使用 state 确定是创建还是删除连接。需要使用 connectorsTicket 来创建连接。

处理“连接器启用”通知

处理“连接器启用”通知：

通过使用外部连接列表 API 查询所有连接，确定要创建的Microsoft Graph 连接 (连接数以及每个连接) 的架构。确定是从头开始创建所有连接、恢复 ( (恢复流) 还是当所有所需连接都处于就绪状态时) 无操作 (。
连接以草稿状态创建。将 connectorsTicket 不透明编码的字符串传递到 HTTP 标头中的 GraphConnectors-Ticket 连接创建 API。
注册架构。
成功创建或更新架构后，连接应处于就绪状态。

处理“连接器禁用”通知

处理“连接器禁用”通知：

通过使用外部连接列表 API 查询所有连接，确定要删除的Microsoft Graph 连接。
使用外部连接删除 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

你需要在响应 Microsoft Graph 时发送 202 - Accepted 状态代码。如果 Microsoft Graph 未收到 2xx 类代码，它会尝试在大约四小时内多次发布更改通知。之后，更改通知将被删除，并且不会传递。

验证 validatonToken 的真实性：

验证令牌是否未过期。
验证令牌是否未被篡改，并由Microsoft 标识平台颁发。
验证 validationToken 中的 appId 声明。
验证 validationToken 中的 aud 声明是否与指定的“{{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 应用连接创建时，需要从收到的有效负载发送 connectorTickets 作为 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 连接器通知中提供的值。
应从通知的租户的Microsoft 标识平台获取 {{accessToken}} 。

响应

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

注意

可以为创建的连接启用各种Microsoft 365 体验。有关详细信息，请参阅 Microsoft Graph连接器概述。

若要了解如何将外部项引入工作Microsoft Graph 连接，请参阅创建、更新和删除应用程序通过 Microsoft Graph 连接器添加的项目。

通过在 Teams 管理中心启用 Microsoft Graph 连接器来验证体验

验证体验：

以租户的 Teams 管理员或全局管理员身份登录到 Teams 管理中心。
选择左侧栏选项卡中的“ 管理应用” 边栏选项卡。
转到 Teams 应用程序。
在 Teams 应用的详细信息页上，你注意到一个新的 Graph 连接器 选项卡，允许管理员启用或禁用 Microsoft Graph 连接器。
选择切换按钮，将启用或禁用通知发送到应用的通知终结点，由应用清单中的 graphConnector.notificationUrl 属性指定。

使 Microsoft Graph 连接器可用于 Teams 管理中心中的其他组织

可以将打包为跨 Microsoft 365 的 Teams 应用的 Microsoft Graph 连接器提交到 Microsoft合作伙伴中心。这允许Microsoft验证 Microsoft Graph 连接器，以便其他组织可以在 Microsoft Teams 管理中心中发现和部署它。

可以使用分步提交指南来了解如何提交应用。确保在市场产品/服务的Microsoft 365 和 Copilot 选项卡中提交 Teams 应用。

你需要在 “其他认证信息” 步骤中提交 PDF。 Microsoft使用此 PDF 中提供的信息来确保 Microsoft Graph 连接器在智能 Microsoft 365 Copilot 副驾驶® 中按预期执行。 PDF 必须包含以下部分：

测试帐户、许可证密钥和凭据
自定义垂直名称
语义标签
示例提示
连接说明
活动设置

测试帐户、许可证密钥和凭据

在演示租户上创建一个用户帐户，Microsoft可用于验证 Microsoft Graph 连接器。可以在Microsoft 365 管理中心的“用户”部分中完成此操作。确保此新用户帐户具有智能 Microsoft 365 Copilot 副驾驶®许可证。

在 PDF 的此部分中，提供此新用户帐户的凭据和任何适用的许可证密钥。此信息是必需的。若要详细了解如何准备用户帐户进行验证，请参阅提供测试说明的最佳做法。

Microsoft验证应用后，可以撤销对用户帐户的访问权限。

自定义垂直名称

创建仅返回自定义 Microsoft Graph 连接器的结果的自定义垂直。在“搜索 & 智能门户”的“自定义”选项卡的“垂直”部分中执行此操作。在 PDF 的此部分中，提供此自定义垂直的名称。自定义垂直的名称是必需的。

语义标签

在“语义标签”部分中，指示连接架构中的 title哪些属性具有、 url和 iconUrl 语义标签。此架构映射是必需的。

示例提示

在“示例提示”部分中，提供两个示例提示，Microsoft可用于在智能 Microsoft 365 Copilot 副驾驶® 中验证 Microsoft Graph 连接器。这些提示应至少包含与语义标签的部分匹配 title 。这些提示是必需的。

连接说明

在“连接说明”部分中，提供 description 自定义 Microsoft Graph 连接的属性。 Microsoft使用它来确保Microsoft Graph 连接具有智能 Microsoft 365 Copilot 副驾驶®的丰富说明。此说明是可选的。

活动设置

在“活动设置”部分中，提供与 urlToItemResolvers 资源的 Microsoft Graph 连接的活动设置。活动设置是可选的，但我们强烈建议提供它们。

通过