Windows Search プロバイダー

[アーティクル]
05/09/2024

Note

一部の情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

重要

このトピックで説明する機能は、Windows 11 のビルド 22631.2787 から Windows 10 のビルド 19045.3758 以降の Windows のプレビュービルドで使用できますが、新しいビルドは安定性の向上が含まれているため推奨されます。 Windows のプレビュービルドについては、「Windows 10 Insider プレビュー」を参照してください。

Windows Search は現在、Microsoft Bing アプリの Web Search を使用して、Web コンテンツと検索結果を返します。欧州経済領域 (EEA) では、Web 検索プロバイダーを実装するインストール済みのアプリを有効にして、[設定] を通じて Windows Search で Web コンテンツと検索結果を返すことができます。

検索プロバイダーは、検索プロバイダーを登録するために OS に必要な情報を提供するパッケージマニフェストファイルを使用して MSIX パッケージを作成することで、Search エクスペリエンスと統合されます。ユーザーは、関連付けられているアプリパッケージをインストールして Windows に検索プロバイダーを追加し、Windows 設定アプリの [プログラムの追加と削除] ページから検索プロバイダーを削除できます。

開発とテストの場合、開発者モードが有効で、検索プロバイダーアプリがデバイスにサイドロードされている場合、そのアプリは利用可能な検索プロバイダーのリストに表示されます。詳細については、「開発者モードの機能とデバッグ」を参照してください。

検索プロバイダーが OS に登録されると、標準化されたクエリ文字列を使用して、パッケージマニフェストでプロバイダーによって指定された HTTP エンドポイントにユーザークエリが渡されます。エンドポイントは、提案された結果を JSON ドキュメントで返します。検索プロバイダーには、応答ドキュメントに推奨される各 URL と共に、プレビューエンドポイント URL が含まれています。この URL は、検索結果 UI のプレビューウィンドウに表示される HTML ドキュメントを返します。

この記事では、検索プロバイダーアプリパッケージを作成するためのガイダンスと、検索プロバイダーの HTTP エンドポイントを実装するためのプロトコルの詳細について説明します。

検索機能拡張アプリパッケージを作成する

検索プロバイダーは、検索プロバイダーの名前や、検索候補とプレビューの HTTP エンドポイントなど、プロバイダーに関する必要な情報を含む MSIX パッケージを提供することで、OS に登録します。

検索プロバイダーアプリ拡張機能

アプリパッケージマニフェストファイルでは、Windows アプリのさまざまな拡張機能と機能がサポートされています。アプリケーションパッケージマニフェストの形式は、パッケージマニフェストスキーマリファレンスに記載されているスキーマのセットによって定義されます。検索プロバイダーは、uap3:AppExtension 内で登録情報を宣言します。拡張機能の Name 属性は、"com.microsoft.windows.websearchprovider" に設定する必要があります。

検索プロバイダーには、uap3:AppExtension の子として uap3:Properties を含める必要があります。パッケージマニフェストスキーマでは、適切な形式の XML を必要とする以外に、uap3:Properties 要素の構造は適用されません。このセクションの残りの部分では、検索プロバイダーを正常に登録するために 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

Protocol

エンドポイント

OS が検索クエリ要求を送信する HTTPS エンドポイントの URL。

Protocol

指定された Web 検索結果を起動するときに使用されるプロトコルスキーマ。指定したプロトコルが OS 上のアプリによって登録されていない場合は、既定のブラウザーが起動して検索結果が表示されます。プロトコルスキーマの登録の詳細については、「uap:Protocol」を参照してください。

DynamicContentEndpoint

検索ボックスに光るアイコンを表示するためのリクエストを OS が送信する HTTPS エンドポイントの URL。詳細については、「光るアイコンのエンドポイントを実装する」を参照してください。この機能は、Windows 10 ビルド 19045.4233 および Windows 11 ビルド 22621.3371 以降でサポートされています。

パッケージマニフェストファイルの例

Windows Search プロバイダーを登録するためのパッケージマニフェストファイルの例 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 Search プロバイダーの候補エンドポイントを実装する

検索プロバイダーは、ユーザーが 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 ドキュメントを返す必要があります。キー名は、正確に形式と一致する必要があります。

Key	説明
サジェスチョン	ユーザークエリに関連付けられた提案を表すキー `Attributes` を持つ JSON オブジェクトの一覧が含まれます。
属性	提案の属性が含まれます。
url	プロバイダー Web サイトの検索候補の URL。
query	検索候補に関連付けられているユーザークエリ。
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 Search プロバイダープレビューエンドポイントを実装する

検索プロバイダーは、検索結果の各候補に関連付けられたページの HTML プレビューを提供する HTTPS エンドポイントの URL を返します。プレビューエンドポイント応答は、機能しているページの 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 に送信され、検索プロバイダーは、アイコン画像ファイルの URL およびその他のメタデータを含む、以下で定義された形式の json ファイルで応答します。検索プロバイダーが Windows Search でアクティブになっている最新のプロバイダーである間、光るアイコンの要求が定期的に送信されます。この要求の頻度は 6 時間ごとです。要求は、検索の起動時やデバイスのロック解除時にも送信されます。

Gleam アイコン 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	クライアントデバイスの OS。このパラメーターの値には「Windows 10」または「Windows 11」を指定できます。 Windows 10 では、光るアイコンのサイズは 30 x 60 です。 Windows 11 では、光るアイコンのサイズは 20 x 36 です
schemaversion	光るスキーマのバージョン。

光るアイコン応答 JSON 形式

検索プロバイダーの光るアイコンの HTTPS エンドポイントは、次の形式の JSON ドキュメントを返す必要があります。キー名は、正確に形式と一致する必要があります。現在のスキーマバージョンは 1.0.0 です。

キー	説明
schemaVersion	光るスキーマのバージョン。これは、要求内の schemaVersion クエリ文字列パラメータと一致する必要があります。
telemetryId	光るアイコンの一意の識別子。応答の値が現在の光るアイコンの値と同じである場合、OS はアイコンを更新しません。
expirationTime	光るアイコンの有効期限。将来の日付にする必要があります。
content	応答のコンテンツセクション。
taskbarSearchBox	検索ボックスの設定が含まれています。
光	光るアイコンの設定が含まれています。
altText	光るアイコンの代替テキスト。
dimensionEnum	要求が Windows 10 デバイスから送信された場合の値は「30 x 60」です。要求が Windows 10 デバイスから送信された場合の値は「20 x 36」です。
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 内の 240 x 120px フレーム内にある必要があります。

空のペイロードを受信した場合、アクティブな光るアイコンがクリアされ、光は表示されなくなります。

次の方法で共有

Windows Search プロバイダー

検索機能拡張アプリパッケージを作成する

検索プロバイダーアプリ拡張機能

要素の階層

エンドポイント

Protocol

DynamicContentEndpoint

パッケージマニフェストファイルの例

Windows Search プロバイダーの候補エンドポイントを実装する

提案 HTTPS 要求の形式

提案 HTTPS 応答ヘッダー

提案応答の JSON 形式

Windows Search プロバイダープレビューエンドポイントを実装する

プレビュー HTTPS 要求の形式

プレビュー HTTPS 応答ヘッダー

光るアイコンエンドポイントを実装する

Gleam アイコン HTTPS 要求の形式

光るアイコン応答 JSON 形式

光るアイコンの応答検証

その他のリソース

次の方法で共有

Windows Search プロバイダー

検索機能拡張アプリ パッケージを作成する

検索プロバイダー アプリ拡張機能

要素の階層

エンドポイント

Protocol

DynamicContentEndpoint

パッケージ マニフェスト ファイルの例

Windows Search プロバイダーの候補エンドポイントを実装する

提案 HTTPS 要求の形式

提案 HTTPS 応答ヘッダー

提案応答の JSON 形式

Windows Search プロバイダー プレビュー エンドポイントを実装する

プレビュー HTTPS 要求の形式

プレビュー HTTPS 応答ヘッダー

OPTIONS 要求とクロスオリジン リソース共有 (CORS)

光るアイコン エンドポイントを実装する

Gleam アイコン HTTPS 要求の形式

光るアイコン応答 JSON 形式

光るアイコンの応答検証

関連記事

その他のリソース

検索機能拡張アプリパッケージを作成する

検索プロバイダーアプリ拡張機能

パッケージマニフェストファイルの例

Windows Search プロバイダープレビューエンドポイントを実装する

OPTIONS 要求とクロスオリジンリソース共有 (CORS)

光るアイコンエンドポイントを実装する