Windows 搜尋提供者

發行項
05/09/2024

注意

針對發行前產品的部分相關資訊，在產品正式發行時可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

重要

本主題中所述的功能可在 Windows 預覽版本中使用 (從 Windows 11 版本 22631.2787 和 Windows 10 版本 19045.3758 開始)，但建議使用較新的版本，因為新版本在穩定性方面有所改善。如需 Windows 預覽版本的資訊，請參閱 Windows 10 Insider Preview。

Windows 搜尋目前使用 Microsoft Bing 應用程式中的 Web 搜尋，來傳回 Web 內容和搜尋結果。在歐洲經濟區 (EEA) 中，您可以啟用已安裝的應用程式，以實作網頁搜尋提供者，透過設定在 Windows 搜尋中傳回網頁內容和搜尋結果。

搜尋提供者會藉由建立 MSIX 套件與套件資訊清單檔案來整合搜尋體驗，該檔案會提供作業系統註冊搜尋提供者的必要資訊。使用者可以透過 Microsoft Store 安裝相關聯的應用程式套件新增搜尋提供者至 Windows，並可透過 Windows 設定應用程式的新增或移除程式頁面移除搜尋提供者。

若要進行開發和測試，當啟用開發人員模式且裝置上已側載搜尋提供者應用程式時，它會出現在可用的搜尋提供者清單中。如需詳細資訊，請參閱開發人員模式功能和偵錯。

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

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

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

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

搜尋提供者應用程式延伸模組

應用程式套件資訊清單檔案支援 Windows 應用程式的許多不同延伸模組與功能。應用程式套件資訊清單格式是由一組架構所定義，記載於套件資訊清單的結構描述參考。搜尋提供者會在 uap3:AppExtension 中宣告其註冊資訊。延伸模組的 Name 屬性必須設定為「com.microsoft.windows.websearchprovider」。

搜尋提供者應該包含 uap3:Properties 做為 uap3:AppExtension 的子系。套件資訊清單架構不會強制執行 uap3:Properties 元素的結構，只會要求格式正確的 XML。本節的其餘部分說明作業系統對要成功註冊搜尋提供者預期的 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

通訊協定

端點

作業系統將傳送搜尋查詢要求的 HTTPS 端點 URL。

通訊協定

啟動提供的 Web 搜尋結果時將使用的通訊協定結構描述。如果作業系統上的應用程式未註冊指定的通訊協定，則會針對搜尋結果啟動預設瀏覽器。如需註冊通訊協定結構描述的詳細資訊，請參閱 uap:Protocol。

DynamicContentEndpoint

作業系統將向其發送要求，以在搜尋框中顯示閃爍圖示的 HTTPS 端點的 URL。有關更多資訊，請參閱實作閃爍圖示端點。從 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 搜尋方塊中輸入時，搜尋提供者必須公開並註冊作業系統所呼叫的 HTTPS 端點。此端點應該會傳回 JSON 格式化的字串，其中包含所提供使用者查詢的搜尋建議。內容必須透過 HTTPS 傳遞。搜尋整合不支援透過 HTTP 傳遞的內容。

建議 HTTPS 要求格式

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

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

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

參數	描述
setlang	與查詢相關聯的地區設定。
cc	與查詢相關聯的國家/地區代碼。
qry	使用者提供的查詢。如果參數沒有值，也就是在查詢字串中做為 `qry=` 出現，則使用者查詢是空的。搜尋提供者仍然可以提供建議和預覽頁面，以回應空的查詢。注意：作業系統不會執行查詢字串的任何清理。搜尋提供者可以在收到查詢時實作自己的清理。

建議 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。
query	與搜尋建議相關聯的使用者查詢。
previewPaneUrl	預覽端點的 URL，您可以從中擷取建議的 HTML 預覽。
Text	建議的文字描述。

{"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 要求。

實作閃爍圖示端點

搜尋提供者可以選擇提供淺色和深色模式閃爍圖示，目前啟用搜尋提供者時，這些圖示會顯示在搜尋列中。當應用程式清單中提供 DynamicContentEndpoint 元素時，要求將會傳送到指定的 URL，搜尋提供者將使用下方定義的格式 json 檔案回應，其中包括圖示影像檔案的 URL 和其他中繼資料。當搜尋提供者是 Windows 搜尋中最新的活動提供者時，將定期傳送閃爍圖示要求。此要求的頻率是每 6 小時一次。每次搜尋啟動和裝置解鎖時也會傳送要求。

閃爍圖示 HTTPS 要求格式

閃爍圖示端點的 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	用戶端裝置的作業系統。此參數的值可以是「Windows10」或「Windows11」。在 Windows 10 上，閃爍圖示大小為 30x60。在 Windows 11 上，閃爍圖示大小為 20x36
schemaversion	閃爍結構描述版本。

閃爍圖示回應 JSON 格式

閃爍圖示的搜尋提供者 HTTPS 端點必須傳回 JSON 文件，格式如下。索引鍵名稱必須完全符合格式。目前的結構描述版本為 1.0.0。

關鍵	描述
schemaVersion	閃爍結構描述版本。這應該與要求中的 schemaVersion 查詢字串參數相符。
telemetryId	閃爍圖示的唯一識別碼。如果回應中的值與目前閃爍圖示的值相同，作業系統將不會更新圖示。
expirationTime	閃爍圖示的到期時間。一定是未來的某個時間。
content	回應的內容部分。
taskbarSearchBox	包含搜尋方塊的設定。
閃爍	包含閃爍圖示的設定。
altText	閃爍圖示的替代文字。
dimensionEnum	如果要求是從 Windows 10 裝置傳送的，則值為「30x60」。如果要求是從 Windows 11 裝置傳送的，則值為「20x36」。
iconUrl	包含淺色和深色閃爍圖示影像檔案的 URL。
light	淺色閃爍圖示影像檔案的 URL。
dark	深色閃爍圖示影像檔案的 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>"
        }
      }
    }
  }
}

閃爍圖示回應驗證

回應必須同時指定淺色資產 URL 和深色資產 URL。圖示影像 URL 的網域必須使用 HTTPS，且子網域必須與應用程式資訊清單檔案中 DynamicContentEndpoint 元素指定的子網域相符。

影像檔案必須為 SVG 格式，最大檔案大小為 300 KB。閃爍需要位於 SVG 內的 240x120px 框架中。

如果收到空的承載，則會清除使用中的閃爍圖示，並且不會顯示任何閃爍。

共用方式為

Windows 搜尋提供者

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

搜尋提供者應用程式延伸模組

元素階層

端點

通訊協定

DynamicContentEndpoint

範例套件資訊清單檔案

實作 Windows 搜尋提供者建議端點

建議 HTTPS 要求格式

建議 HTTPS 回應標頭

建議回應 JSON 格式

實作 Windows 搜尋提供者預覽端點

預覽 HTTPS 要求格式

預覽 HTTPS 回應標頭

實作閃爍圖示端點

閃爍圖示 HTTPS 要求格式

閃爍圖示回應 JSON 格式

閃爍圖示回應驗證

其他資源

共用方式為

Windows 搜尋提供者

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

搜尋提供者應用程式延伸模組

元素階層

端點

通訊協定

DynamicContentEndpoint

範例套件資訊清單檔案

實作 Windows 搜尋提供者建議端點

建議 HTTPS 要求格式

建議 HTTPS 回應標頭

建議回應 JSON 格式

實作 Windows 搜尋提供者預覽端點

預覽 HTTPS 要求格式

預覽 HTTPS 回應標頭

OPTIONS 要求和跨原始來源資源共用 (CORS)

實作閃爍圖示端點

閃爍圖示 HTTPS 要求格式

閃爍圖示回應 JSON 格式

閃爍圖示回應驗證

相關文章

其他資源