连接机器人进行搜索（预览）

本文介绍如何创建自定义联合搜索提供程序（由机器人提供支持），并将其连接到搜索通道。 租户管理员在其租户中启用提供商后，来自 Office.com、SharePoint.com 和 Bing.com 的企业用户搜索可以包括你的自定义搜索提供者的结果。

使用 Azure 联合搜索平台，可以构建自定义联合搜索提供程序，以允许你的信息参与 Azure 搜索的 答案和垂直体验，而无需将该信息与 Microsoft 365 索引合并。 有关详细信息，请参阅宣布推出 Azure 联合搜索平台的开发人员预览版和 Dynamics 365 联合搜索（预览版）。

将机器人连接到搜索通道需要执行以下步骤。 本文稍后将更详细地介绍这些步骤。

1. 实现机器人以充当搜索提供程序。
2. 如果机器人要求用户登录：
   1. 在Azure 门户中，向搜索平台公开机器人 API。
   2. 在机器人代码中，使用生成的范围 URI 生成用户令牌。
3. 将机器人部署到 Azure。
4. 将搜索通道添加到机器人。
5. 请 IT 管理员查看机器人注册并在租户中发布机器人。

先决条件

• 了解 Bot Framework 服务的基础知识，以及使用 Bot Framework SDK 创建机器人的方式。
• 要连接到该通道的机器人。
• 如果你没有 Azure 帐户，则可以在开始前创建试用版订阅。

可以使用 Bot Framework SDK 支持的任何语言实现机器人。 本文以 C# 联合搜索机器人 为例。

公开机器人 API 以搜索

在某些业务工作流中，机器人可能需要用户凭据才能代表用户执行操作。 若要在搜索通道中为机器人创建单一登录（SSO）体验，必须允许搜索平台代表用户保护来自 Microsoft Entra ID 的访问令牌。

若要为机器人生成范围 URI 和应用程序 ID，请执行以下操作：

1. 转到 Azure 门户。
2. 如果还没有机器人资源，则创建一个 Azure 机器人资源。
3. 转到 Microsoft Entra ID 服务。
4. 转到应用注册窗格。
5. 选择与机器人关联的应用程序。
6. 转到公开 API 窗格。
7. 选择添加范围。
   1. 在添加范围窗格中，建议保留自动生成 的应用程序 ID URI。 选择保存并继续。
   2. 输入范围名称。
   3. 对于谁可以同意？，管理员和用户是首选选项，但这两个选项都可以。
   4. 输入一个管理员同意显示名称和一个管理员同意说明。
   5. 可选，输入一个用户同意显示名称和一个用户同意说明。
   6. 确认状态设置为已启用。
   7. 选择“添加作用域”。
8. 选择添加客户端应用程序。
   1. 在添加客户端应用程序窗格中，将客户端 ID 设置为81473081-50b9-469a-b9d8-303109583ecb，搜索平台的客户端 ID。
   2. 在授权范围下，选择在上一步中创建的范围 URI。
   3. 选择“添加应用程序”。
9. 转到概述窗格。 复制应用程序 ID URI。 在搜索通道中注册机器人时，需要用到它。

实现你的机器人

搜索通道将每个用户查询作为调用活动发送到机器人，其名称为“application/search”。 机器人在调用响应中返回查询结果。 对发回搜索通道的查询结果使用自适应卡片格式。

1. 将项目中的任何 Bot Framework 和自适应卡片包更新到最新版本。
2. 可选 添加身份验证代码 以生成用户令牌。
3. 为要包含的每个数据源实现数据搜索方法 。
4. 生成自适应卡片以显示结果。

获取搜索平台跟踪 ID

搜索平台为发送到机器人的每个查询分配唯一的跟踪 ID。 平台将此添加到调用活动的通道数据。 你可能决定记录请求的跟踪 ID。 使用通道数据 traceId 的属性获取跟踪 ID。

在 联合搜索示例中，SearchHelper.GetSearchTraceId 方法演示如何从调用活动获取跟踪 ID。

添加身份验证

如果将机器人 API 公开为搜索，并在将机器人连接到搜索时请求身份验证，则可以从活动的通道数据获取用户身份验证令牌。

通道数据 authorizations 的属性可以包含身份验证令牌列表。 如果向搜索公开机器人 API，则列表将包含代表令牌。 列表中的令牌具有以下结构：

属性名称	类型​​	描述
authType	integer	身份验证令牌类型：对于未知或默认使用 0，或对于委托令牌使用 2。
token	string	身份验证令牌本身。

在 联合搜索示例中：

• SearchBotAuthenticationToken 类和 AuthenticationTypes 枚举表示此信息。
• SearchHelper.GetSearchOboToken 方法演示如何从调用活动获取令牌。

获得令牌后，可以在请求用户的任何受保护资源时使用它。 有关使用委托令牌的信息，请参阅 Microsoft 标识平台和 OAuth 2.0 代理流。

查询每个数据存储

搜索通道将查询作为 invoke 活动发送到机器人，查询的详细信息在活动的 value 属性中，该属性表示一个具有以下结构的 JSON 对象：

属性名称	类型​​	描述
queryText	string	查询文本。
kind	string	查询的类型：“search”表示结果将显示在自定义垂直选项卡中，或者“searchAnswer”表示结果将作为答案显示在全部选项卡中。
queryOptions	object	用于分页的其他查询选项。
queryOptions.skip	integer	要发送的第一个结果的索引。
queryOptions.top	integer	要发送的最大结果数。

在调用响应中返回搜索结果：

• 始终将调用响应对象的 Status 属性设置为 200，指示网络连接正常。 对象的 Body 属性具有单独的状态代码。

• 该 Body 属性表示具有以下结构的 JSON 对象：

  属性名称	类型​​	说明
  statusCode	integer	用于指示机器人是否能够成功运行查询的 HTTP 状态代码。
  type	string	调用响应的类型，定义值字段的格式。 将“application/vnd.microsoft.search.searchResponse”用于搜索结果，或将“application/vnd.microsoft.error”用于错误消息。
  value	对象 (object)	与值相对应的值 type。

  对于错误消息，value 对象包含：

  属性名称	类型​​	说明
  code	string	由机器人定义的错误代码，如未指定则为 null。
  message	string	错误消息，如未指定则为 null。

  对于搜索结果，该 value 对象包含：

  属性名称	类型​​	描述
  结果	搜索结果对象的数组	结果，如无则为 null。
  displayLayouts	显示布局对象的数组	显示布局，如无则为 null。
  totalResultCount	integer	如果支持分页，则提供的总结果;否则，为 null。
  moreResultsAvailable	布尔	指示是否有更多可用结果。

  搜索结果对象包含：

  属性名称	类型​​	说明
  value	string	此搜索结果的唯一标识符或值。
  layoutId	string	要用于此结果的显示布局的 ID。
  data.searchResultText	字符串	此结果的文本。

  显示布局对象包含：

  属性名称	类型​​	描述
  layoutId	字符串	布局。
  layoutBody	字符串	布局正文作为自适应卡片 JSON 对象。

在 联合搜索示例中，SearchHelper.RunFederatedSearch 方法演示如何从调用活动获取查询信息以及如何设置调用响应的格式。

显示搜索结果

可以创建搜索垂直和结果类型，以定制用户在 SharePoint、Office 和必应中进行搜索时看到的搜索结果。 垂直选项使用户更容易找到他们有权限查看的信息。 有关详细信息，请参阅 支持的自适应卡片元素 部分。

如果机器人收到没有响应的查询，则其回复应包含空响应。

在 Azure 中注册机器人

若要将机器人连接到搜索通道，必须在 Azure 中预配机器人资源。 有关详细信息，请参阅如何将机器人注册到 Azure，以及如何在 Azure 中部署机器人。

连接机器人进行搜索

以下说明演示如何将机器人连接到搜索。

1. 转到 Azure 门户。

2. 打开机器人资源。

3. 打开 频道（预览） 窗格。

4. 选择“搜索”。

5. 在搜索设置选项卡中，输入机器人的信息。

   

   1. 在搜索提供程序元数据下，输入在搜索 UI 中显示的名称。

   2. 在触发短语下，定义表示机器人可以回答的查询的短语。

      注意

      对于初始版本，仅提供英语（en-US）。

      • 上传包含短语的 .csv 文件。 该文件应包含一列数据，没有标题。
      • 从语言首选项列表中，选择在其中编写触发短语的语言。

   3. 在身份验证下，指示搜索提供程序是否需要用户身份验证。

      • 如果需要身份验证，请输入身份验证 URL。 使用为机器人公开 API 时复制的应用程序 ID URI。

   4. 选择下一步。

6. 在垂直选项卡中，如果希望搜索提供程序的结果显示在搜索结果页中自己的自定义垂直中，请在字段中输入垂直名称;否则，请将此字段留空。 然后选择下一步。
   搜索结果页适用于 Office.com、SharePoint.com 和 Bing.com。

7. 在租户发布选项卡中，查看设置并添加发布信息。

   1. 查看搜索提供程序名称和示例查询。 如有必要，请返回上一个选项卡以更改此信息。
   2. 输入搜索提供程序的说明。
   3. 支持联系人电子邮件。 使用有权访问搜索提供程序的开发人员或开发人员组的电子邮件。

8. 选择添加以请求 IT 管理员批准。

在租户中批准搜索提供程序

租户中的搜索提供程序审批由 Microsoft 365 管理中心的搜索&智能页中的 IT 管理员进行。

测试连接

建议在生产环境中启用搜索提供程序之前在测试租户中启用搜索提供程序。

修改搜索提供程序

在提交搜索提供程序以供 IT 管理员审阅之前，可以编辑搜索提供程序。 如果初始请求被拒绝或服务已停用，则可能需要执行此操作。

1. 在Azure 门户中，转到包含你想要编辑的搜索提供程序的机器人资源。
2. 转到 频道（预览） 窗格。
3. 选择 搜索 通道，然后选择 编辑。
   1. Azure 显示 搜索通道 窗格。 在此窗格中，可以编辑设置。
   2. 若要修改触发短语，请下载文件，在本地编辑该文件，然后上传文件。
   3. 完成编辑后，再次选择 添加 以提交搜索提供程序以供 IT 管理员审阅。

删除搜索提供程序

若从机器人资源中删除搜索通道，你的搜索提供程序将被删除。

若要从机器人中删除搜索通道，请执行以下命令：

1. 在 Azure 门户中，转到你的 Azure 机器人资源。
2. 转到频道（预览） 窗格。
3. 选择搜索图标。
4. 在搜索频道窗格顶部，选择删除通道。
5. 选择是以确认操作。

删除机器人资源：

1. 在 Azure 门户中，转到你的机器人资源。
2. 如果尚未这样做，请从机器人中删除搜索通道。
3. 在概述窗格的顶部，选择删除。
4. 选择确定确认操作。

其他信息

搜索通道使用联合搜索和自适应卡片架构：

有关自适应卡片架构的详细信息，请参阅机器人开发人员的自适应卡片。

关于触发短语

触发短语是搜索平台使用的短语，用于将查询定向到由你的机器人提供支持的自定义搜索提供程序。 当语句与其中一个触发短语匹配时，联合搜索会将用户的语句转发到搜索提供程序。

例如，考虑管理航班计划和状态的机器人。

1. 请考虑用户引用或使用机器人的几种常见方法。 请务必将机器人与其他机器人区分开来。

   使用更具体的短语（如“飞行时间表”和“航班时间表”）而不是适用于学校和电视节目的“时间表”等一般术语。

2. 包括涵盖机器人功能范围的各种短语，例如出发时间和当前状态。

   例如，包括有关：到达或出发时间和机场的查询。

此类 航班计划和状态 机器人的触发短语可能包括：

• 航班时间表
• 航班动态
• 航班 675 出发时间
• 我的航班何时出发
• 航班 468 到达时间
• 西雅图塔科马航班动态
• 希思罗机场航班动态

作为另一个示例，天气预报机器人的触发短语可能包括：

• 本地天气预报
• 天气信息
• 明天的天气
• 近10天的天气预报
• 今天的最高温度
• 今天会下雨吗
• 明天会下雪吗
• 明天的风速
• 外面是否风
• 伦敦天气

支持的自适应卡片元素

联合搜索支持自适应卡片架构的子集。 有关设置搜索结果格式的信息，请参阅 自定义搜索结果页。

支持包括以下自适应卡片元素：TextBlock、RichTextBlock、Image、ColumnSet、ImageSet 和 FactSet。 有关详细信息，请参阅 Microsoft 搜索的管理搜索结果布局和自适应卡片架构资源管理器。

可以直接将每个卡创作为 JSON，也可以使用 AdaptiveCards NuGet 包。

联合搜索不支持 HTML

搜索平台不包含 HTML 分析程序。 但是，可以消除一些标记，并使用 Html2Markdown NuGet 包将 HTML 转换为 Markdown：

1. 删除 <span> 和 <u> 元素。
2. 将 <div> 和 <br> 元素替换为段落 （<p>） 元素。
3. 将剩余的 HTML 转换为 Markdown。

后续步骤

• 有关机器人连接器服务中通道支持的信息，请参阅将机器人连接到通道。
• 有关生成机器人的信息，请参阅机器人的工作原理和使用 Bot Framework SDK 创建机器人快速入门指南。
• 有关部署机器人的信息，请参阅部署机器人和设置持续部署。