通过

Windows 搜索 网页搜索提供商

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

Windows 搜索 UI 截图，包含第三方搜索提供程序集成。

搜索提供程序通过创建 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。

动态内容端点

不再支持此功能。 有关详细信息，请参阅 实现 gleam 图标终结点。 OS 将发送请求至 HTTPS 终结点，其 URL 用于显示搜索框中的 gleam 图标。

示例包清单文件

下面是用于注册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=

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

参数 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）

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

实现 gleam 图标终结点

注释

此 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

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

参数 DESCRIPTION
setlang 与查询关联的区域设置。
抄送 与查询关联的国家/地区代码。
日期时间 客户端设备的当前日期和时间（URL 编码）。
设备操作系统 客户端设备的 OS。 此参数的值可以是“Windows10”或“Windows11”。 在Windows 10，闪闪发光图标大小为 30x60。 在Windows 11，闪闪发光图标大小为 20x36
schemaversion gleam 架构版本。

Gleam 图标响应 JSON 格式

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

密钥 DESCRIPTION
schemaVersion gleam 架构版本。 这应与请求中的 schemaVersion 查询字符串参数匹配。
遥测ID 闪亮图标的唯一标识符。 如果响应中的值与当前 gleam 图标的值相同，OS 将不会更新该图标。
过期时间 闪光图标的过期时间。 必须是将来的某个时间。
内容 响应的内容部分。
任务栏搜索框 包含搜索框的设置。
微光 包含 gleam 图标的设置。
altText 闪光图标的替代文本。
dimensionEnum 如果请求是从Windows 10设备发送的，则值为“30x60”。 如果请求是从Windows 11设备发送的，则值为“20x36”。
iconUrl 包含浅色和深色闪闪发光图标图像文件的 URL。
光 闪光图标图像文件的 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 内的 240x120像素帧内。

如果收到空的有效负载时，活动的闪烁图标将会被清除，并且不会显示任何闪烁。

  • Last updated on