创建、更新和删除 Microsoft Graph 中的连接

项目
11/07/2024

Microsoft Graph 连接器平台提供了将外部数据添加到Microsoft Graph 的直观方法。连接是外部数据的逻辑容器，管理员可将其作为一个单元进行管理。

创建连接后，可以从任何外部数据源（例如本地内容源或外部软件即服务 (SaaS) 服务）添加内容。只能查看并管理已创建或已显式授权管理的连接。搜索管理员可以从现代管理中心查看和管理租户中的所有连接。

自定义支持系统票证连接器结构示例。

示例自定义帮助台系统票证连接器结构。

连接的管理员视图，包括自定义票证连接器。

连接的管理员视图，包括自定义票证连接器。

可以根据需要对连接进行建模，但为连接器的每个实例创建连接是最常见的模型。例如，每次设置 Microsoft Windows 文件共享连接器时，都会新建连接。你还可以创建一个连接来添加数据源中的所有项目。例如，可以创建单个连接，从而从帮助台系统跨多个团队添加所有票证和事件。

状态与操作

你的连接可以以下列一种状态存在。

状态	说明
Draft	已设置空连接。未配置任何数据源、架构或设置。
Ready	该连接配有已注册的架构并已准备好接收。
Obsolete	如果已弃用依赖功能（如 API），则会出现这种情况。删除连接是唯一有效的操作。
LimitExceeded	如果达到单个连接的最大限制或所有连接的租户级别配额，则在退出状态之前，无法添加更多项。

下表指定每种状态中的可用操作。

Operation	Draft	Ready	Obsolete	LimitExceeded
Create Connection	❌	✔️	❌	✔️
Read connection	✔️	✔️	✔️	✔️
更新连接	✔️	✔️	❌	✔️
删除连接	✔️	✔️	✔️	✔️
创建架构	✔️	❌	❌	❌
读取架构	❌	✔️	✔️	✔️
更新架构	❌	❌	❌	❌
删除架构	❌	❌	❌	❌
创建项目	❌	✔️	❌	❌
读取项目	❌	✔️	✔️	✔️
更新项目	❌	✔️	❌	✔️
删除项目	❌	✔️	❌	✔️

通过连接，应用程序可以为将编制索引的项定义架构，并为服务提供终结点，从而从索引添加、更新或删除项。

应用程序将项添加到搜索索引的第一步是创建连接。

创建连接

应用程序必须先创建并配置连接，然后才可将项添加到搜索索引:

使用唯一 ID、显示名称和说明创建连接。
注册架构，以定义索引中将包含的字段。

注意： 有关更新现有连接的架构的详细信息，请参阅架构更新功能。

连接设置

可以为每个已启用的内容体验配置默认连接设置。启用后，这些设置会影响内容体验。

搜索设置

通过在 searchSettings 中提供内容的默认搜索显示模板，可以定义搜索结果在“Microsoft搜索结果”页中的显示方式。一组搜索显示模板可用于以不同方式显示不同类型的搜索结果。搜索显示模板具有使用自适应卡片和指定一个或多个条件的规则生成的结果布局。满足这些条件时，布局将应用于搜索结果并显示在结果页上。

活动设置

在活动设置中，你可以为 Microsoft 365 个应用提供一种方法来检测共享活动，从而向与该内容交互最多的用户推荐你的内容。为此，请添加 urlToItemResolver。这允许在 Microsoft 365 应用中检测到的连接 URL 解析为 externalItem 上的相应项 ID。

下图显示了项目在跨 Microsoft 365 的建议体验中的显示方式。

以下示例显示了 activitySettings 有效负载，其中包含完整的 urlToItemResolvers 部分。例如，当有人共享链接 https://contoso.com/items/39483948/时，它表示通过 Microsoft Graph 连接引入的 externalItem 。在此示例中，共享链接表示 itemId 为的 id_39483948externalItem。此连接指定如何从 URL 映射到该 externalItem 的 itemId。在此示例中，此连接的 ID 为 contosohr。

通过在连接上发送修补请求来更新活动设置。

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

以下 activitySettings 有效负载随修补程序请求一起发送。

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

在此示例中， itemId 字段指定了如何形成 URL 表示的外部项的 ID。 itemId 在 urlMatchInfo) urlPattern (中引用，以提取39483948为 externalItem 的 ID。

可以在 urlToItemResolvers 资源中为活动设置有效负载提供最多 8 个 itemIdResolver 资源的列表。对于其中每个 urlMatchInfo 资源，请为指定值#microsoft.graph.externalConnectors.itemIdResolver，为 @odata.type优先级属性指定一个介于 1 到 8 之间的整数，并为 urlMatchInfo 对象指定一个包含基 URL 列表和正则表达式的 urlMatchInfo 对象。

共享链接时，将按优先级值指定的顺序应用属于解析程序的 urlMatchInfo 对象。按升序优先级顺序，首先将 URL 与 urlMatchInfo 属性中 baseUrls 列表中的 URL 进行比较。然后，如果链接 URL 的基在 baseUrls 列表中，则 urlPattern 正则表达式将应用于 URL。如果此模式匹配，则不会再应用任何解析程序。如果链接 URL 的基不在 baseUrls 列表中，或者 urlPattern 无法匹配，则会计算下一个 urlToItemResolver ，直到找到匹配项，或者没有其他 urltoItemResolver 资源要应用。

若要详细了解 urlMatchInfo 资源，请参阅 urlMatchInfo 类型。

更新连接

若要更改现有连接的显示名称、说明或启用的内容体验，可以更新连接。

删除连接

要删除所有已通过连接编制索引的项，可以删除连接。

通过