共用方式為

Windows 搜尋網路搜尋引擎提供者

Windows 搜尋目前使用 Microsoft Bing 的網頁搜尋應用程式來回傳網頁內容與搜尋結果。 在歐洲經濟區（EEA），你可以安裝實作網頁搜尋服務的應用程式，以便在 Windows 搜尋中回傳網頁內容和搜尋結果。

Windows搜尋介面與第三方搜尋服務整合的截圖。

搜尋提供者會藉由建立 MSIX 套件 與套件指令清單檔案來整合搜尋體驗，以提供作系統註冊搜尋提供者的必要資訊。 安裝後，搜尋服務在 Windows 搜尋體驗中預設啟用。 在 Windows 設定中，使用者可以啟用或停用已安裝的搜尋服務提供者，並管理搜尋結果中提供者的順序。 使用者可透過Windows設定中的 Settings > Apps > Installed Apps 頁面移除搜尋服務提供者。

若要進行開發和測試，當啟用開發人員模式且裝置上已側載搜尋提供者應用程式時，它會出現在可用的搜尋提供者清單中。 欲了解更多資訊，請參閱 開發者設定。

向OS註冊搜尋提供者之後，用戶查詢會使用標準化查詢字串，傳遞至提供者在其套件指令清單中指定的 HTTP 端點。 端點會在 JSON 檔中傳回建議的結果。 在回應檔中每個建議的 URL 時，搜尋提供者會包含預覽端點 URL，它會傳回在搜尋結果 UI 中預覽窗格中顯示的 HTML 檔。

本文提供建立搜尋提供者應用程式套件的指引，以及實作搜尋提供者 HTTP 端點之通訊協定的詳細數據。

建立搜尋擴充性應用程式套件

搜尋提供者會藉由提供 MSIX 套件來向 OS 註冊，其中包含提供者的必要資訊，例如搜尋提供者的名稱，以及建議和預覽的 HTTP 端點。

搜尋工具應用程式擴充功能

應用程式套件清單檔案支援多種不同的 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 搜尋結果時將使用的通訊協議架構。 如果作系統上的應用程式未註冊指定的通訊協定，則會針對搜尋結果啟動預設瀏覽器。 如需註冊通訊協議架構的詳細資訊，請參閱 uap：Protocol。

動態內容端點 (DynamicContentEndpoint)

不再支援此功能。 如需詳細資訊，請參閱 建立 Gleam 圖示端點。 作業系統將把一個請求發送到 HTTPS 端點的網路位址，以便將 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 搜尋提供者建議端點

搜尋提供者必須公開並註冊一個 HTTPS 端點，當使用者輸入 Windows 搜尋框時，作業系統會呼叫該端點。 此端點應該會傳回 JSON 格式的字串，其中包含所提供使用者查詢的搜尋建議。 內容必須透過 HTTPS 傳遞。 搜尋整合不支援透過 HTTP 傳遞的內容。

建議 HTTPS 要求格式

建議端點的 HTTPS 要求會使用下列格式。

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

傳遞至建議端點的查詢字串參數如下。

參數 說明
setlang 與查詢相關的地區設定。
副本 與查詢相關聯的國家/地區代碼。
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 預覽端點的 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

傳遞至建議端點的查詢字串參數如下。

參數 說明
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 請求及跨原始來源資源分享（CORS）

搜尋提供者必須支援 OPTIONS 要求方法，並使用 HTTP OK 回應此要求。 如果搜尋提供者端點使用 CORS，Windows 搜尋客戶端會在每次 GET 請求前發送 HTTP OPTIONS 請求。

實現 Gleam 圖示接口端點

備註

此 Gleam 功能已不再啟用。 不再顯示於歐洲經濟區所有網路服務提供者的 Gleam 圖示。 本文件的此部分內容已過時。

搜尋提供者可以選擇性地提供亮色和暗色模式的光芒圖示，這些圖示會在搜尋提供者啟用時顯示於搜尋欄中。 當在應用程式指令清單中提供 DynamicContentEndpoint 元素時，系統會將要求傳送至指定的 URL，而搜尋提供者會以下列所定義格式的 json 檔案回應，其中包含圖示圖像檔和其他元數據的 URL。 當搜尋服務提供者是 Windows 搜尋中最新啟用的服務提供者時，閃光圖示請求會定期發送。 此要求的頻率是每隔 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 與查詢相關的地區設定。
副本 與查詢相關聯的國家/地區代碼。
日期時間 來自客戶端裝置的目前日期和時間，URL 編碼。
裝置作業系統 用戶端裝置的 OS。 此參數的值可以是 「Windows10」 或 「Windows11」。。 在 Windows 10 上，閃光圖示大小為 30x60。 在 Windows 11 中，閃光圖示大小為 20x36
schemaversion Gleam 架構版本。

Gleam 圖示反應 JSON 格式

gleam 圖示的搜尋提供者 HTTPS 端點必須傳回 JSON 檔，格式如下。 索引鍵名稱必須完全符合格式。 目前的架構版本為 1.0.0。

鑰匙 說明
schemaVersion Gleam 架構版本。 這應該符合要求的 schemaVersion 查詢字串參數。
telemetryId Gleam 圖示的唯一識別碼。 如果回應中的值與目前 Gleam 圖示的值相同，OS 將不會更新圖示。
到期時間 Gleam 圖示的到期時間。 必須是未來的某個時間點。
內容 回應內容區段。
工作列搜尋框 包含搜尋方塊的設定。
微光 包含 Gleam 圖示的設定。
altText Gleam 圖示的替代文字。
dimensionEnum 如果請求是從 Windows 10 裝置傳送，則為「30x60」。 如果請求是從 Windows 11 裝置發送，則為「20x36」。
圖示網址 包含淺色和深光閃閃圖示影像檔案的URL。
光線 淺色 Gleam 圖示影像檔的 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 的 240x120px 框架內。

如果收到空的資料包，將會清除作用中的 Gleam 圖示，不會顯示任何 Gleam。

  • Last updated on