Windows 搜索 网页搜索提供商

Windows搜索当前使用来自Microsoft 必应应用的 Web 搜索返回 Web 内容和搜索结果。 在“欧洲经济区”（OEC），可以安装实现 Web 搜索提供程序的应用，以在Windows搜索中返回 Web 内容和搜索结果。

搜索提供程序通过创建 MSIX 包 和包清单文件来集成搜索体验，该文件提供 OS 注册搜索提供程序所需的信息。 安装后，在Windows搜索体验中默认启用搜索提供程序。 在“Windows设置”中，用户可以启用和禁用已安装的搜索提供程序，并在搜索结果中管理提供程序的顺序。 用户可以通过 Windows 设置中的 Settings > Apps > Installed apps 页面删除搜索提供程序。

为了进行开发和测试，当启用开发人员模式并且搜索提供程序应用已在设备上旁加载时，它将显示在可用搜索提供程序列表中。 有关详细信息，请参阅 开发人员的设置。

向 OS 注册搜索提供程序后，将使用标准化查询字符串将用户查询传递到提供程序在其包清单中指定的 HTTP 终结点。 端点在 JSON 文档中返回推荐结果。 对于响应文档中每个建议的 URL，搜索提供程序包括预览终结点 URL，该 URL 返回在搜索结果 UI 的预览窗格中显示的 HTML 文档。

本文提供有关创建搜索提供程序应用包的指南，以及有关实现搜索提供程序 HTTP 终结点的协议的详细信息。

创建搜索扩展性应用包

搜索提供程序通过提供包含有关提供程序的必需信息的 MSIX 包（例如搜索提供程序的名称和用于建议和预览的 HTTP 终结点）向 OS 注册。

搜索供应商应用扩展

应用包清单文件支持Windows应用的许多不同扩展和功能。 应用包清单格式由 包清单架构引用中记录的一组架构定义。 搜索提供程序在 uap3：AppExtension 中声明其注册信息。 扩展的 Name 属性必须设置为“com.microsoft.windows.websearchprovider”。

搜索提供程序应包含 uap3：Properties 作为 uap3：AppExtension 的子级。 包清单架构不强制实施 uap3：Properties 元素的结构，只要求格式良好的 XML。 本部分的其余部分介绍 OS 期望的 XML 格式，以便成功注册搜索提供程序。

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Search provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

元素层次结构

uap3：属性

  端点

  协议

端点

OS 将向其发送搜索查询请求的 HTTPS 终结点的 URL。

协议

启动提供的 Web 搜索结果时要使用的协议架构。 如果 OS 上的应用未注册指定的协议，则会针对搜索结果启动默认浏览器。 有关注册协议架构的详细信息，请参阅 uap：Protocol。

示例包清单文件

下面是用于注册Windows搜索提供程序的 appmanifest.xml 包清单文件的示例。

<!-- appxmanifest.xml -->

  <uap3:Extension Category="windows.appExtension">
	  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
		  <uap3:Properties>
			  <Endpoint>https://customsearchendpoint</Endpoint>
			  <Protocol>customsearch</Protocol>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

实现Windows搜索提供商建议端点

搜索提供程序必须在用户键入Windows搜索框时公开和注册 OS 调用的 HTTPS 终结点。 此终结点应返回 JSON 格式的字符串，其中包含提供的用户查询的搜索建议。 内容必须通过 HTTPS 传递。 搜索集成不支持通过 HTTP 传递的内容。

建议 HTTPS 请求格式

对建议终结点的 HTTPS 请求使用以下格式。

https://contoso.com?setlang=en-US&cc=US&qry=

传递给建议终结点的查询字符串参数如下。

参数	DESCRIPTION
setlang	与查询关联的区域设置。
抄送	与查询关联的国家/地区代码。
qry	用户提供的查询。 如果参数没有值，即在查询字符串 qry=中显示为空，则用户查询为空。 搜索提供程序仍可以提供建议和预览页面，以响应空查询。 注意 OS 不对查询字符串执行任何清理。 当收到查询时，搜索提供程序可以实现其自己的清理。

建议 HTTPS 响应标头

搜索提供程序必须在建议 HTTPS 终结点的响应中包含以下标头。

• Access-Control-Allow-Origin： https://www.bing.com
• Access-Control-Allow-Credentials：真
• Access-Control-Allow-Methods：GET
• Content-Type：application/json;charset=utf-8
• 内容长度：[必须是响应的确切长度]

响应建议的 JSON 格式

搜索建议提供程序的 HTTPS 终结点必须返回以下格式的 JSON 文档。 键名称必须与格式完全匹配。

密钥	DESCRIPTION
建议	包含 JSON 对象列表，其中包含表示与用户查询关联的建议的键 Attributes 。
特性	包含建议的属性。
网址	供应商网站上的搜索建议的网络地址。
查询	与搜索建议关联的用户查询。
预览窗口URL	可以从该预览终结点的 URL 检索建议的 HTML 预览。
文本	建议的文本说明。

{"Suggestions": 
   [{"Attributes": 
     {"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"}, 
    {"Attributes": 
     {"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
    ] 
} 

实现 Windows 搜索提供程序预览端点

搜索提供程序返回 HTTPS 终结点的 URL，该终结点提供与搜索结果中每个建议关联的页面的 HTML 预览。 预览终结点响应必须返回正常运行页面的 HTML 代码。

预览 HTTPS 请求格式

对预览终结点的 HTTPS 请求使用以下格式。

https://contoso.com?Darkschemeovr=1

传递给建议终结点的查询字符串参数如下。

参数	DESCRIPTION
Darkschemeovr	指定调用Windows系统是否已启用深色主题。 如果启用了深色主题，则值为 1;如果禁用深色主题，则值为 0。

预览 HTTPS 响应标头

• Access-Control-Allow-Origin： https://www.bing.com
• Access-Control-Allow-Credentials：真
• Access-Control-Allow-Methods：GET
• Content-Type：text/html;charset=utf-8
• 内容长度：[必须是预览 html 的确切长度]

OPTIONS 请求和跨域资源共享 （CORS）

Windows 搜索客户端在每个 GET 请求之前都会发送 HTTP OPTIONS（CORS 预检）请求。 搜索提供程序必须支持 OPTIONS 请求方法，并使用 HTTP 200 OK 进行响应。

相关文章