通过

通过 Microsoft Graph 连接器创建、更新和删除应用程序添加的项目

  • 项目

Microsoft Graph 连接器提供了一种直观的方法，可将外部数据添加到 Microsoft Graph 中。 应用程序添加到 Microsoft 搜索服务的项由 Microsoft Graph 中的 externalItem 资源表示。

创建连接 后，可以添加内容。 数据源中的每个项目都必须用唯一的项目 id 表示为 Microsoft Graph 中的 externalItem。 此 ID 用于在 Microsoft Graph 中创建、更新或删除项目。 可以将数据源中的主键用作项目 ID，或者从一个或多个字段派生项目 ID。

主要组件

externalItem 有三个关键组成部分：访问控制列表、属性和内容。

访问控制列表

访问控制列表 (ACL) 用于指定是否授予或拒绝给定角色访问权限，以在 Microsoft 体验中查看项目。 ACL 是一个访问控制项数组，表示Microsoft Entra用户或组。 第三个访问控制条目类型 Everyone 表示租户中的所有用户。

访问控制列表示例。

访问控制列表示例。

accessType 值 deny 优先于 grant。 例如，在以前显示的项目中，如果授予 Everyone 访问权限，并且拒绝了特定用户的访问权限，则此用户的有效权限将被 deny。

如果数据源具有用于设置项目权限的非 Azure Active Directory 组（例如技术支持系统中的团队），则可以通过使用组同步 API 复制 allow 或 deny 权限来在 Microsoft Graph 中创建外部组。 避免将外部组的成员身份直接展开为各项的 ACL，因为每个组成员资格都可能导致大量项目更新。

外部组包括另一个组、Microsoft Entra用户和Microsoft Entra组。 如果有非 Azure AD 用户，则必须将其转换为 ACL 中的Microsoft Entra用户。

属性

属性组件用于添加在 Microsoft Graph 体验中有用的项元数据。 在向该连接添加项目并将数据类型转换为支持的数据类型前，必须注册该架构。

属性组件示例。

属性组件示例。

内容

内容组件添加需要为全文编制索引的项的批量内容。 示例包括票证说明、文件正文中的已分析文本或者 wiki 网页正文。

内容是影响 Microsoft 体验相关性的关键字段之一。 支持内容类型 text 和 html。 如果数据源具有其他内容类型，如二进制文件、视频或图像，则可以在将它们添加到 Microsoft Graph 之前将其解析为文本。 例如，光学字符识别可以从图像中提取可搜索文本。

重要

合规性解决方案仅支持 text 内容类型。 如果通过将 enabledContentExperience 属性设置为 compliance来启用符合性连接，则应引入纯文本格式的内容并将内容类型设置为 text。

内容设置为文本的内容组件插图。

内容组件的示例。

无法直接将内容添加到搜索结果模板中，但可以使用生成的结果片段，它是内容中相关节的动态生成的预览。

搜索结果模板的屏幕截图。

搜索结果模板。

数据源中的内容发生更改时，必须将其与连接项同步。 可以更新整个项目，也可以更新一个或多个组件。 将内容添加到 Microsoft Graph 后，可以在设置垂直搜索和结果类型或使用 Microsoft Graph 搜索 API 后，通过 Microsoft 搜索体验进行搜索。

活动

活动组件是一个暂时性属性，用于对项发送 活动 。 只能写入此属性。

活动包括执行活动) 的执行组件 (、执行活动的时间 () ，以及 () 执行的活动类型的活动类型。 当前支持的活动类型可在 externalActivity 的 type 属性的“说明”部分找到。

对项发送活动可跨 Microsoft 365 提供智能建议体验。 最终用户可以根据发送的活动接收为其量身定做的内容。

添加项

要向索引添加项，请 创建 externalItem。 创建项目时，可在 URL 中分配唯一的标识符。

例如，你的应用程序可能会使用票证编号来索引支持人员票证。 如果票证具有票证编号 SR00145，则请求外观可能如下所示：

PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

"properties": {
  "title": "WiFi outage in Conference Room A",
  "priority": 1,
  "assignee": "meganb@contoso.com"
}

注意

管理员必须先为相应的连接 自定义搜索结果页，然后才能在 Microsoft 搜索 UI 中找到索引项。

向项添加活动

若要向项添加活动，请调用 addActivities 终结点，该终结点在 URL 中具有与该项相同的唯一标识符。

例如，如果在 2022 年 4 月 11 日下午 4：25，Microsoft Entra ID18948b93-d3ed-4307-9981-10fc36a08a52在支持人员工单上注释了票证编号SR00145，则发送该活动的请求可能如下所示。

POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json

"activities": [
 {
   "type": "commented",
   "startDateTime": "2022-04-11T16:25:34.3202005Z",
   "performedBy": {
       "id": "18948b93-d3ed-4307-9981-10fc36a08a52",
       "type": "user"
    }
  }
]

还可以将活动添加到创建该项的同一请求中的项。 将活动添加为另一个实体，例如 acl 和 content。 如果以这种方式添加活动，请为活动包括 @odata.type ，否则请求将失败。 时间戳超过 7 天的活动不会显示在 Microsoft 365 应用中。 最终用户只能在 Microsoft 365 应用中查看他们可以访问的项目的活动，并在 (上拥有活动，例如，与他们共享、创建、编辑等) 。

更新项

当项在外部服务中更新（重新分配支持人员票证或更新产品说明）时，可以使用创建项时分配给项的唯一标识符，通过 更新 externalItem 更新它在索引中的条目。

PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

{
  "assignee": "alexw@contoso.com"
}

删除项

要从索引中删除项，可以使用创建项时分配给项的唯一标识符来 删除 externalItem。

DELETE /external/connections/contosohelpdesk/items/SR00145

使数据保持同步

选择如何保持数据同步时，请考虑以下信息：

爬网机制：

  • 增量爬网：检测并推送源数据中的添加项;与完全爬网相比，性能密集型更少。
  • 完全爬网：汇报源数据中的整个项， (重新爬网) ，捕获所有添加和删除操作;确保更好的准确性，但比增量爬网更耗时、更耗费性能。

同步间隔：

  • 基于事件：基于事件推送项更新。 建议将此同步间隔用于动态或敏感数据，例如项目状态。
  • 计划：定期 (每 N 分钟) 推送项更新。 建议将此同步间隔用于更新频率较低的内容丰富或非敏感数据，例如 Wiki 或网页。

最终，数据刷新策略的选择取决于数据类型和计算功能。

后续步骤