Windows 搜索提供程序

项目
05/09/2024

注意

一些信息与预发布产品相关，在商业发行之前可能发生实质性修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

重要

本主题中介绍的功能在 Windows 11 的版本 22631.2787 和 Windows 10 的版本 19045.3758 的预览版本中可用，但建议使用较新的版本，因为它们包含稳定性改进。有关 Windows 预览版的信息，请参阅 Windows 10 Insider Preview。

Windows 搜索当前使用 Microsoft 必应中的 Web 搜索返回 Web 内容和搜索结果。在欧洲经济区 (EEA)，可以启用已安装的应用，实现 Web 搜索提供程序，以通过“设置”在 Windows 搜索中返回 Web 内容和搜索结果。

搜索提供程序通过创建带有程序包清单文件的 MSIX 程序包与搜索体验相集成，该程序包清单文件提供 OS 注册搜索提供程序所需的信息。用户可以通过 Microsoft Store 安装关联的应用包将搜索提供程序添加到 Windows，并通过 Windows 设置应用中的添加或删除程序页删除搜索提供程序。

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

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

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

创建搜索扩展性应用包

搜索提供程序通过提供包含提供程序必需信息（例如搜索提供程序的名称以及建议和预览的 HTTP 终结点）的 MSIX 包向操作系统注册。

搜索提供程序应用扩展

应用包清单文件支持适用于 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:Properties

EndPoint

协议

端点

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

协议

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

DynamicContentEndpoint

HTTPS 终结点的 URL，操作系统将向其发送在搜索框中显示 Gleam 图标的请求。有关详细信息，请参阅实现 Gleam 图标终结点。从 Windows 10 内部版本 19045.4233 和 Windows 11 内部版本 22621.3371 开始，支持此功能。

示例程序包清单文件

下面是用于注册 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>
        <DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
		  </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=

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

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

建议 HTTPS 响应标头

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

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

建议响应 JSON 格式

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

键	说明
建议	包含 JSON 对象列表，其中包含表示与用户查询关联的建议的键 `Attributes`。
特性	包含建议的属性。
url	提供程序网站上的搜索建议的 URL。
查询	与搜索建议关联的用户查询。
previewPaneUrl	可从中检索建议的 HTML 预览的预览终结点的 URL。
文本	建议的文本说明。

{"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

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

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

预览 HTTPS 响应标头

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

搜索提供程序必须支持 OPTIONS 请求方法，并使用 HTTP OK 响应此请求。如果搜索提供程序终结点使用的是 CORS，则 Windows 搜索客户端将在每个 GET 请求之前发送 HTTP OPTIONS 请求。

实现 Gleam 图标终结点

搜索提供程序可以选择提供浅色模式和深色模式 Gleam 图标，当当前启用搜索提供程序时，这些图标显示在搜索栏中。当在应用清单中提供 DynamicContentEndpoint 元素时，将向指定的 URL 发送请求，搜索提供程序使用下面定义的格式（包括图标图像文件的 URL 和其他元数据）的 json 文件进行响应。当搜索提供程序是 Windows 搜索中处于活动状态的最新提供程序时，Gleam 图标请求将定期发送。此请求的节奏为每 6 小时一次。每次启动搜索和设备解锁时也会发送一个请求。

Gleam 图标 HTTPS 请求格式

对 Gleam 图标的 HTTPS 请求使用以下格式。

https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0

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

参数	说明
setlang	与查询关联的区域设置。
cc	与查询关联的国家/地区代码。
dateTime	客户端设备的当前日期和时间（URL 编码）。
deviceOs	客户端设备的 OS。该参数的值可以是“Windows10”或“Windows11”。在 Windows 10 上，Gleam 图标大小为 30x60。在 Windows 11 上，Gleam 图标大小为 20x36
schemaversion	Gleam 架构版本。

Gleam 图标响应 JSON 格式

Gleam 图标的搜索提供程序 HTTPS 终结点必须返回采用以下格式的 JSON 文档。键名称必须与格式完全匹配。当前架构版本为 1.0.0。

密钥	说明
schemaVersion	Gleam 架构版本。这应与请求中的 schemaVersion 查询字符串参数匹配。
telemetryId	Gleam 图标的唯一标识符。如果响应中的值与当前 Gleam 图标的值相同，OS 将不会更新该图标。
expirationTime	Gleam 图标的过期时间。必须是将来的某个时间。
内容	响应的内容部分。
taskbarSearchBox	包含搜索框的设置。
Gleam	包含 Gleam 图标的设置。
altText	Gleam 图标的替代文本。
dimensionEnum	如果请求是从 Windows 10 设备发送的，则值为“30x60”。如果请求是从 Windows 11 设备发送的，则值为“20x36”。
iconUrl	包含浅色和深色 Gleam 图标图像文件的 URL。
灯	浅色 Gleam 图标图像文件的 URL。
dark	深色 Gleam 图标图像文件的 URL。

{
  "schemaVersion":"1.0.0",
  "telemetryId":"<unique gleam Id>",
  "expirationTime":"2025-12-09T20:37:13Z",
  "content": {
    "taskbarSearchBox": {
      "gleam":{
        "altText": "<alt text of the gleam>",
        "dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
        "iconUrl": {
          "light":"<3p's light gleam url>",
          "dark": "<3p's dark gleam url>"
        }
      }
    }
  }
}

Gleam 图标响应验证

响应必须同时指定浅色资产 URL 和深色资产 URL。图标图像 URL 的域必须使用 HTTPS，子域必须与应用清单文件中 DynamicContentEndpoint 元素中指定的子域匹配。

图像文件必须采用 SVG 格式，最大文件大小为 300 kB。 Gleam 需要位于 SVG 内的 240x120px 帧内。

如果接收到空有效负载，将清除激活的 Gleam 图标，并且不会显示任何 Gleam。

通过

Windows 搜索提供程序

创建搜索扩展性应用包

搜索提供程序应用扩展

元素层次结构

端点

协议

DynamicContentEndpoint

示例程序包清单文件

实现 Windows 搜索提供程序建议终结点

建议 HTTPS 请求格式

建议 HTTPS 响应标头

建议响应 JSON 格式

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

预览 HTTPS 请求格式

预览 HTTPS 响应标头

OPTIONS 请求和跨域资源共享 (CORS)

实现 Gleam 图标终结点

Gleam 图标 HTTPS 请求格式

Gleam 图标响应 JSON 格式

Gleam 图标响应验证

相关文章

其他资源