通过

注册和管理智能 Microsoft 365 Copilot 副驾驶®连接器的架构

本指南提供有关定义架构和遵循智能 Microsoft 365 Copilot 副驾驶®连接器的最佳做法的指导。

连接架构定义如何在智能 Microsoft 365 Copilot 副驾驶®体验中使用内容。 架构是计划添加到连接的所有属性的平面列表。 每个属性包括属性、标签和别名。 在将项添加到连接之前，必须注册架构。

下表显示了工作票证系统连接器的示例架构：

属性 类型 可搜索 可查询 可检索 可精简 需要完全匹配 标签 别名
ticketId String ✔️ ✔️ ID
title String ✔️ ✔️ ✔️ title
createdBy String ✔️ ✔️ createdBy Creator
assignedTo String ✔️ ✔️
lastEditedDate 日期时间 ✔️ ✔️ ✔️ lastModifiedDateTime editedDate
lastEditedBy String ✔️ ✔️ ✔️ lastModifiedBy 已编辑
workItemType String ✔️ ✔️ ticketType
priority Int64 ✔️
标记 StringCollection ✔️ ✔️ ✔️ ✔️
status String ✔️ ✔️
url String url
已解决 Boolean ✔️ ✔️

有关架构对象和 API 参考，请参阅 Copilot 连接器 API 参考中的架构部分。

架构属性

本部分介绍每个架构属性，并提供使用这些属性的最佳做法。

属性

此属性引用属性的名称。

最佳实践：

  • 使用清晰且唯一的名称 - 确保属性名称易于理解和区分。 避免名称不明确，如 orgName、 brOrgName或 tpOrgName。 请改用或 等parentOrganizationNamedepartmentName描述性名称来帮助 Copilot 正确解释属性。
  • 避免过于技术化或神秘的名称 - 将名称（如 dataBlob 或 ftxInvIsLead ）替换为有意义的替代方法（如 incidentRootCause 或 qualifiedSalesLead ）以提高对用户查询的可读性和相关性。
  • 添加属性说明 - 说明可帮助 Copilot 更好地了解属性并将其与用户查询匹配。

注意

2025 年第 4 季度应支持向自定义连接器添加属性说明。
使用声明性代理 (DA) 时，请在 DA 指令集中包括属性说明。

可搜索

当属性标记为可搜索时，其值将添加到全文索引中。 这允许 Copilot 在用户的查询与 属性或其 内容匹配时返回结果。

在如下的情况下将属性标记为可搜索：

  • 它包含用户可能搜索 的文本数据 。
  • 它 与搜索查询 (相关，例如标题、说明、标记) 。
  • 你希望它有助于 搜索命中 数和 代码片段生成。

常见示例：title、 description、 tags、 createdBy、、 assignedTo。

最佳实践：

  • 避免将大型二进制字段标记为可搜索。
  • 不要将可优化字段标记为可搜索，这些属性是相互排斥的。
  • 仅当属性对搜索相关性至关重要时，才将其标记为可搜索。

搜索“设计”，显示针对属性标题和内容的命中结果。

搜索 design 将显示针对属性 (title) 和内容的命中结果。

可查询

如果用户需要根据特定值筛选其搜索结果，请将属性标记为 可查询 。 例如，、 或 created 等ticketIdteamName属性可以查询。 当用户查询类似 tickets created by William的内容时，Copilot 只能筛选并返回相关票证。 前缀与通配符运算符 (*) 匹配可以进一步提高搜索灵活性。

在如下的情况下将属性标记为可查询：

  • 它用于 筛选或缩小搜索结果范围。
  • 它表示 分类或结构化数据 (例如状态、优先级、分配的用户) 。
  • 你想要支持 自定义搜索体验 或 分面导航。

常见示例：

status (例如打开、关闭) 、 assignedTo (例如 userEmail 或 ID) ， priority (例如高、中、低) 、 category或 type。

最佳实践：

  • 避免将大型文本字段 (标记为可查询) 说明。
  • 与 Retrievable: true 结合使用Queryable: true，以便可以使用属性并在结果中显示。
  • 如果希望属性在 UI 中显示为筛选器，请使用Refinable: true 。

在此示例中， tags 标记为可查询：

“tags:design”搜索，将结果范围缩小到标记属性中具有“设计”的项。

搜索将tags:design结果范围缩小到 属性中的tags项design。

如果某个属性可查询，则可以使用 KQL (关键字查询语言) 对其进行查询。 KQL 支持自由文本关键字和属性限制。 属性名称必须显式或以编程方式包含在查询中。 支持使用通配符运算符的前缀匹配 (*) 。

注意

不支持后缀匹配。

搜索“search ba*”，显示与此前缀匹配的结果。 用于 search ba\* 显示与此前缀匹配的结果的搜索。

可检索

如果属性的值应在搜索结果中返回，则将其标记为 可检索 。 显示模板中显示的或从查询返回的任何属性都必须可检索。 具有选择性 - 将过多或大型属性标记为可检索可能会增加搜索延迟。

呈现为结果的一组可检索属性。

一组呈现为结果的可检索属性(title 和 lastEditedBy)。

在出现的情况下，将属性标记为可检索：

  • 你希望它在 搜索结果中可见。
  • 它提供 (上下文信息 ，例如标题、状态、分配的用户) 。

常见示例：
title, summary, description, status, assignedTo, createdDateTime.

最佳实践：

  • 避免将敏感或不相关的字段标记为可检索。
  • 用于Retrievable: true搜索卡、Copilot 提示符或自定义 UI 中显示的字段。

可精简

如果要在 Microsoft搜索体验中将其用作筛选器，请将属性标记为 可精简 。 管理员可以将可精简属性配置为在搜索结果页上显示为自定义筛选器。

当属性可精简时：

  • 它可用于 缩小搜索结果范围。
  • 它显示为 精简条件控件 (例如 UI 中的下拉列表或复选框) 。
  • 它支持搜索查询中的 聚合 。

在如下的情况下将属性标记为可精简：

  • 它表示 分类或结构化数据。
  • 你希望用户按这些值 筛选或分组 结果。

常见示例：
tags (，例如财务、人力资源、工程) 、 status (，例如开放、关闭、正在进行) ， priority (例如高、中、低) 、category、 。 type

最佳实践：

  • 可精简和可搜索是相互排斥的 ， 属性不能同时存在。
  • 只能细化 字符串或数值类型 。
  • 将过多属性标记为可精简可能会影响 性能。

按标记（一种可精简属性）优化结果。 通过 tags来优化结果，这是一个可精简的属性。

需要完全匹配

如果 isExactMatchRequired 属性的 设置为 true ，则会为完整字符串值编制索引。 此设置 只能 应用于 不可搜索的属性。

例如， 属性 ticketId 既可查询，又需要完全匹配：

  • 查询 ticketId:CTS-ce913b61 返回票证 ID 为 CTS-ce913b61 的项目。
  • 查询ticketId:CTS不会返回票证 ID 为 CTS-ce913b61 的项目。

同样， tags 属性也使用完全匹配：

  • 查询 tags:contoso 将返回带有 contoso 标记的项。
  • 查询tags:contoso不会返回带有标记 contoso 票证的项目。

当 属性包含诸如 GUID 之类的值或其他必须完全匹配的标识符时，这尤其有用。 在这种情况下，将 设置为 isExactMatchRequiredtrue。

如果未 isExactMatchRequired 指定 ，则默认为 false。 例如， title 属性 不需要 完全匹配。 它根据项内容的语言规则进行标记化：

  • 查询 title: Contoso Title 返回 Contoso 标题中包含 或 Title 的项目。

语义标签

语义标签是由Microsoft发布的已知标记，你可以将其分配给架构中的属性。 使用 Microsoft 图形 API 生成自定义 Copilot 连接器时，应用语义标签至关重要。 这些标签可帮助智能 Microsoft 365 Copilot 副驾驶®和Microsoft搜索了解每个属性的含义和角色，从而改进搜索、汇总和整体用户体验。

可以使用 图形 API分配语义标签，也可以在使用 SDK 时从“分配属性标签”页分配语义标签。 标签提供语义意义，并允许连接器数据无缝集成到 Microsoft 365 体验中。

例如，不同的项目管理工具 (（如 JIRA、Azure DevOps、Asana) 可能会对创建工作项的用户使用不同的术语，例如 owner、 ownedBy或 assignedTo。 如果属性具有类似的用途，则可以分配 createdBy 语义标签。

可以使用图形 API 或使用 sdk 时从 “分配属性标签 ”页向源属性分配语义标签。 标签提供语义意义，并允许将连接器数据集成到 Microsoft 365 体验中。

标签 说明 适用于字段，例如
title main要在搜索和其他体验中显示的项的名称或标题。 documentTitle、ticketSubject、reportName
url 数据源中项的目标 URL。 用于在其原始系统中打开项的直接链接。 documentLink、ticketUrl、recordUrl
createdBy 标识最初在数据源中创建项的用户。 适用于筛选和上下文。 authorEmail、submittedBy、createdByUser
lastModifiedBy 最近在数据源中编辑项的用户的名称。 editorEmail，updatedBy，lastChangedBy
authors 所有在数据源中参与/协作处理该项的人员的姓名。 authorName， writer， reportAuthor
createdDateTime 在数据源中创建该项的日期和时间。 createdOn、submissionDate、entryDate
lastModifiedDateTime 上次在数据源中修改该项的日期和时间。 lastUpdated、modifiedOn、changeDate
fileName 数据源中文件的名称。 projectUrl、folderLink、groupPage
FileExtension 数据源中文件的扩展名。 documentType、attachmentType、format
iconUrl 图标 URL。 thumbnailUrl， 徽标， previewImage
containerName 容器名称。 例如：项目或 OneDrive 文件夹可以是容器。 projectName、folderName、groupName
containerUrl 容器 URL。 projectUrl、folderLink、groupPage

最佳实践：

  • 添加尽可能多的相关标签，但请确保它们已准确映射。
  • 如果标签与属性的用途不匹配 ，请不要将 标签分配给该属性，否则不正确的映射会降低体验。

重要

属性必须标记为 可检索 ，然后才能映射到标签。

标签 title 是最重要的。 将属性分配给此标签可使连接参与 结果群集体验。 虽然并非所有标签都需要使用，但请确保你分配的标签有意义且准确。

相关性

应用准确映射的语义标签可提高内容通过搜索的可发现性。 Microsoft建议尽可能多地定义以下标签，并按其对发现的影响降序列出：
title、 lastModifiedDateTime、 lastModifiedBy、 url、 fileName 和 fileExtension。

确保标签映射准确。 将标签分配给包含大型内容的属性可能会增加搜索延迟并延迟结果。

排名提示

排名提示可应用于以下文本属性：

  • 可搜索
  • 未映射到语义标签

排名提示有助于确定搜索结果中某些属性的优先级。 可以在 Microsoft 365 搜索管理门户中将其重要性从 默认 设置为 非常高 。 这些提示与其他项属性一起使用，以返回最相关的结果。

配置排名提示：

  1. 转到 Microsoft 365 管理门户中的“ 搜索和智能 ”选项卡。
  2. 选择 “自定义>相关性优化”。

“搜索和智能”选项卡的屏幕截图，其中突出显示了“相关性优化”

  1. 在 “相关性优化”下，选择“ 查看详细信息>”“配置排名提示”。

“相关性优化”选项卡的屏幕截图，其中突出显示了“配置排名提示”

  1. 更改可用源属性的重要性权重。

“相关性优化”选项卡的屏幕截图，其中显示了所选属性的重要性权重

默认结果类型

语义标签还会影响 默认结果类型的 生成方式。 分配 和 content 标签至少title可确保为连接创建结果类型。

带有标题和结果片段的默认结果类型。

带有 title 和结果片段的默认结果类型。

若要增强默认结果体验，请定义以下标签（如果适用）， (按影响) 升序列出：
title、 url、 lastModifiedBy、 lastModifiedDateTime、 fileName 和 fileExtension。

用于分配标签的验证清单：

  • 分配给标签的属性必须标记为 可检索。
  • 属性的 数据类型 必须与标签的预期类型匹配。
  • 每个标签应 只映射到一个属性。

别名

别名 是分配给属性的友好名称。 它们用于查询和可精简属性筛选器，以提高可用性和查询灵活性。

下面是一些实际示例：

属性 可能的别名 用例
createdBy author、owner、submittedBy 用户询问 Who wrote this? 或 Who submitted?
title 主题，标题 用户请求 What’s the subject of this item?
tags 标签、类别 用户请求 Show items tagged with Finance
文件名 documentName、fileName 用户请求 Find file named report.docx
摘要 description， abstract 用户请求 Give me a quick overview

别名的最佳做法：

  • 使用 常见同义词 或 特定于域的术语的别名。
  • 避免过于泛型或不明确的别名。
  • 保持别名 简短直观。

Content 属性

Microsoft Copilot连接器架构支持名为 content的默认属性。 不必像其他属性 (（例如标题、标记等 ) ）一样在架构中定义它。 而是在引入数据时 直接包含在项有效负载中 。

Microsoft Copilot连接器架构包括内置content属性。 与其他属性 (（如 title 或 tags) ）不同，无需在架构中定义它。 而是在数据引入期间 直接包含在项有效负载 中。

属性 content 为：

  • 以语义方式为 文本搜索编制索引。
  • 用于在搜索结果中生成 动态代码段 。
  • 可用于 Copilot 进行 摘要 和 语义理解。

使用 content 属性的最佳做法：

  • 将任何 非结构化数据 添加到 属性， content 使 Copilot 能够有效地执行语义搜索和匹配查询。
  • 对于非结构化或自由格式的内容，请在 字段中包括 、、 rootCause和 descriptioncontent 等summarycomment属性。
  • 仅当需要在 UI 中显示这些属性的完整值时，将这些属性保留为单独的可检索字段。
  • 可以将多个属性 (例如 、 summarydescription) 追加到 content 字段中，以丰富语义理解。

引入数据时如何使用 content 属性的示例：

{ 
"@odata.type": "microsoft.graph.externalItem", 
"acl": [ 
{ 
"type": "everyone", 
"value": "everyone", 
"accessType": "grant" 
} 
], 

"properties": { 
"title": "Payment Gateway Error", 
"priority": "High", 
"assignee": "john.doe@contoso.com" 
}, 

"content": { 
"value": "Rootcause : Error in payment gateway : MoreDetails about the error.......", 
"type": "text" 
} 
}

声明性代理和属性说明

如果使用声明性代理 (DA) ，则应在提供给代理的指令集中包括 Copilot 连接器架构的属性说明。 这有助于 DA 了解：

  • 每个属性的语义含义
  • 如何 引用和汇总 数据
  • 如何使用索引内容响应用户查询

为所有属性定义清晰、格式正确的说明。 一个很好的说明应该解释：

  • 属性表示的内容
  • 任何备用名称或术语
  • 何时以及如何使用它

架构更新功能

本部分概述了 架构 API 的更新功能。

注意

更新架构后，建议对项重新编制索引，使其与最新架构保持一致。 如果不重新引入，项行为可能不一致。

添加属性

可以向架构添加新属性。 虽然不需要重新引入，但建议这样做。 添加属性时，包括所有必要的搜索属性。

添加或删除搜索功能

可以修改属性的搜索属性。 然而：

  • 不能将可精简属性添加为架构更新的一部分。
  • 属性不能既可搜索又可精简。

添加或删除搜索功能 需要重新引入。

添加或删除别名

可以添加或删除用于搜索查询的别名。 但是，无法删除系统为可优化属性自动创建的别名。

添加或删除语义标签

可以分配或删除语义标签。 这些标签会影响相关性和Viva Topics等体验。

后续步骤