创建、更新和删除应用程序在 Microsoft Graph 连接中添加的项目Create, update, and delete items added by your application in the Microsoft Graph connection

应用程序添加到 Microsoft 搜索服务的项用 Microsoft Graph 中的 externalItem 资源表示。Items added by your application to the Microsoft Search service are represented by the externalItem resource in Microsoft Graph.

重要

Microsoft Graph 连接器当前处于公共预览状态。Microsoft Graph connectors are currently in public preview status. 为了获取对连接器功能的访问权限,必须在租户中打开目标发布选项。To gain access to connectors functionality, you must turn on the Targeted release option in your tenant. 有关详细信息,请参阅连接器预览计划See more details on the connectors preview program.

创建连接后,可以添加内容。Once you have created a connection, you can add your content. 数据源中的每个项目都必须用唯一的项目 id 表示为 Microsoft Graph 中的 externalItem。此 id 用于在 Microsoft Graph 中创建、更新或删除项目。Each item from your data source must be represented as an externalItem in Microsoft Graph with a unique item id. This id is used to create, update or delete the item from Microsoft Graph. 你可以将数据源中的主键用作 itemId,或者从一个或多个字段派生。You can use the primary key from your data source as the itemId or derive it from one or more fields. externalItem 有三个关键组成部分:访问控制列表、属性和内容。An externalItem has three key components: access control list, properties, and content.

访问控制列表Access control list

访问控制列表用于指定是否授予或拒绝给定角色访问 Microsoft 体验中的查看项目的权限。The access control list is used to specify whether the given roles are granted or denied access to view items in Microsoft experiences. 它是一组访问控制项,每个项表示一个 Azure Active Directory 用户或组。It is an array of access control entries, each representing an Azure Active Directory user or group. 有第三个访问控制条目类型 Everyone ,表示租户中的所有用户。There is a third access control entry type Everyone that represents all the users in the tenant.

访问控制列表示例

AccessType 值 deny 优先于 grantThe accessType value deny takes precedence over grant. 例如,在上面显示的项目中,如果授予 Everyone 访问权限,并且拒绝了特定用户的访问权限,则此用户的有效权限将被 denyFor example, in the item shown above, while Everyone is granted access and a specific user is denied access, the effective permission for this user is deny.

如果数据源具有非 Azure Active Directory 组(例如支持人员系统中的团队),并且用于设置项目的权限,则可以使用组同步 API 复制 allowdeny 权限,在 Microsoft Graph 中创建外部组。If your data source has non Azure Active Directory groups, such as teams within your helpdesk system, used to set permissions for the item, you can create external groups in Microsoft Graph using the group sync APIs to replicate the allow or deny permissions. 避免将外部组的成员身份直接展开为各项的访问控制列表,因为每个组成员身份更新可能会导致项更新的风暴。Avoid expanding the membership of your external groups directly into the access control lists of individual items since each group membership update could lead to a storm of item updates.

外部组可以由另一个外部组、Azure Active Directory 用户和 Azure Active Directory 组组成。External groups can consist of another external group, Azure Active Directory users, and Azure Active Directory groups. 如果你有非 Azure Active Directory 用户,则必须在访问控制列表中将其转换为 Azure Active Directory 用户。If you have non-Azure Active Directory users, you must translate them to Azure Active Directory users in your access control list.

属性Properties

属性组件用于添加在 Microsoft Graph 体验中有用的项元数据。The properties component is used to add item metadata that is useful in Microsoft Graph experiences. 在向该连接添加项目并将数据类型转换为支持的数据类型前,必须注册该架构You must register the schema for the connection before adding items into it and convert datatypes into supported datatypes.

属性组件示例

内容Content

内容组件用于添加需要进行全文检索的大量项目。The content component is used to add the bulk of the item that needs to be full text indexed. 示例包括票证说明、文件正文中的已分析文本或者 wiki 网页正文。Examples include ticket description, parsed text from a file body, or a wiki page body.

内容是影响 Microsoft 体验相关性的关键字段之一。Content is one of the key fields influencing relevance across Microsoft experiences. 我们支持类型 textHTML的内容。We support content of the type text and HTML. 如果数据源有二进制文件,则可以先将它们分析为文本,然后再将其添加到 Microsoft Graph。If your data source has binary files, you can parse them to text before adding them to Microsoft Graph.

内容组件示例

无法直接将内容添加到搜索结果模板中,但你可以使用生成的结果段,该片段是内容中的相关节的动态生成的预览。Content cannot be directly added into a search result template, but you can use a generated result snippet which is a dynamically generated preview of the relevant sections within content.

搜索结果模板的屏幕截图

数据源中的内容发生更改时,必须将其与连接项同步。When content in your data source changes, you must sync it with your connection items. 可更新整个项目或更新它的一个或多个组件。You can either update the entire item or update one or more of its components. 将内容添加到 Microsoft Graph 后,你可以在设置纵向和结果类型或使用 Microsoft Graph 搜索 API 后,通过 Microsoft 搜索体验搜索该内容。Once your content has been added to Microsoft Graph, you can search for it through the Microsoft Search experience after setting up verticals and result types or using the Microsoft Graph Search API.

添加项Add an item

可通过创建 externalItem,将项添加到索引。You can add an item to the index by creating an externalItem. 创建项目时,可在 URL 中分配唯一的标识符。When you create an item, you assign a unique identifier in the URL.

例如,你的应用程序可能会使用票证编号来索引支持人员票证。For example, your application may index helpdesk tickets using the ticket number. 如果票证具有 SR00145 票证编号,请求可能如下所示。If a ticket has the ticket number SR00145, the request may look like the following.

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

{
  "title": "WiFi outage in Conference Room A",
  "status": "New",
  "assignee": "meganb@contoso.com"
}

![注意] 管理员必须先自定义相应连接的搜索结果页,然后索引项才能在 Microsoft 搜索 UI 中找到。![NOTE] Before indexed items can be found in the Microsoft Search UI, an administrator must customize the search results page for the corresponding connection.

更新项Update an item

当项在外部服务中更新(重新分配支持人员票证或更新产品说明)时,可以使用创建项时分配给项的唯一标识符,通过更新 externalItem 更新项在索引中的条目。When an item is updated in the external service (helpdesk ticket is reassigned, or a product description is updated), you can update its entry in the index by updating the externalItem, using the unique identifier assigned to the item when you created it.

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

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

删除项Delete an item

可以使用创建项时分配给项的唯一标识符,通过删除 externalItem 从索引中删除项。You can remove items from the index by deleting the externalItem, using the unique identifier assigned to the item when you created it.

DELETE /external/connections/contosohelpdesk/items/SR00145

后续步骤Next steps