Windows Search Web 検索プロバイダー

2025-05-10

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

検索プロバイダーは、検索プロバイダーを登録するために OS に必要な情報を提供するパッケージマニフェストファイルを使用して MSIX パッケージを作成することで、Search エクスペリエンスと統合されます。インストール後、Windows 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:プロパティ

エンドポイント

プロトコル

エンドポイント

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

プロトコル

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

ダイナミックコンテンツエンドポイント

この機能はサポートされなくなりました。詳細については、「輝くアイコンエンドポイントを実装する」を参照してください。検索ボックスに表示される輝きアイコンの要求を OS が送信する HTTPS エンドポイントの URL。

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

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
アクセス制御許可メソッド: GET
Content-Type: application/json;charset=utf-8
Content-Length: [正確な応答長にする必要があります]

提案応答の JSON 形式

検索プロバイダーの検索候補の HTTPS エンドポイントは、次の形式の JSON ドキュメントを返す必要があります。キー名は、正確に形式と一致する必要があります。

鍵	説明
推奨事項	ユーザークエリに関連付けられている提案を表すキー `Attributes` を持つ JSON オブジェクトの一覧が含まれています。
属性	提案の属性を格納します。
URL	プロバイダー Web サイトの検索候補の URL。
問い合わせ	検索候補に関連付けられているユーザークエリ。
プレビューウィンドウURL	提案の 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
アクセス制御許可メソッド: GET
Content-Type: text/html;charset=utf-8
Content-Length: [プレビュー html の正確な長さにする必要があります]

検索プロバイダーは OPTIONS 要求メソッドをサポートし、HTTP OK でこの要求に応答する必要があります。検索プロバイダーエンドポイントが CORS を使用している場合、Windows 検索クライアントは、各 GET 要求の前に HTTP OPTIONS 要求を送信します。

きらめくアイコンエンドポイントを実装する

注

この輝く機能は有効ではなくなりました。 EEA のすべての Web プロバイダーに対して Gleam アイコンが表示されなくなりました。ドキュメントのこのセクションの内容は廃止されています。

検索プロバイダーは、必要に応じて、検索プロバイダーが現在有効になっているときに検索バーに表示される明るいモードと暗いモードの輝きアイコンを提供できます。アプリマニフェストで DynamicContentEndpoint 要素が指定されると、要求が指定された URL に送信され、検索プロバイダーは、アイコンイメージファイルとその他のメタデータの URL を含む、以下で定義されている形式の json ファイルで応答します。検索プロバイダーが Windows Search でアクティブな最新のプロバイダーである間、輝くアイコン要求が定期的に送信されます。この要求の頻度は 6 時間ごとです。また、検索の起動時とデバイスのロック解除時にも要求が送信されます。

HTTPS 要求形式のGleamアイコン

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	クエリに関連付けられている国コード。
日時	クライアントデバイスからの現在の日付と時刻(URL エンコード)。
デバイスOS	クライアントデバイスの OS。このパラメーターの値には、"Windows10" または "Windows11" を指定できます。 Windows 10 では、輝きアイコンのサイズは 30 x 60 です。 Windows 11 では、輝きアイコンのサイズは 20 x 36 です
schemaversion	gleam スキーマのバージョン。

Gleam アイコン応答 JSON 形式

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

鍵	説明
スキーマバージョン	gleam スキーマのバージョン。これは、要求の schemaVersion クエリ文字列パラメーターと一致する必要があります。
テレメトリーID	輝きアイコンの一意の識別子。応答の値が現在の輝きアイコンの値と同じ場合、OS はアイコンを更新しません。
有効期限	輝きアイコンの有効期限。必ず将来の時間である必要があります。
内容	応答のコンテンツセクション。
タスクバー検索ボックス	検索ボックスの設定が含まれています。
きらめく	輝きアイコンの設定が含まれています。
altText	輝きアイコンの代替テキスト。
dimensionEnum	要求が Windows 10 デバイスから送信された場合の値 "30x60"。要求が Windows 11 デバイスから送信された場合の値 "20x36" です。
アイコンURL	明るい光と暗い輝くアイコンの画像ファイルの URL が含まれています。
光	光の輝くアイコン画像ファイルの 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 内の 240 x 120px フレーム内にある必要があります。

空のペイロードを受信すると、アクティブな輝きアイコンがクリアされ、輝きは表示されません。

次の方法で共有

Windows Search Web 検索プロバイダー

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

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

要素階層

エンドポイント

プロトコル

ダイナミックコンテンツエンドポイント

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

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

提案 HTTPS 要求の形式

提案する HTTPS 応答ヘッダー

提案応答の JSON 形式

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

HTTPS 要求形式のプレビュー

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

OPTIONSリクエストとクロスオリジンリソースシェアリング (CORS)

きらめくアイコン エンドポイントを実装する

HTTPS 要求形式のGleamアイコン

Gleam アイコン応答 JSON 形式

Gleam アイコンの応答検証

関連資料

フィードバック

その他のリソース

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

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

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

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

きらめくアイコンエンドポイントを実装する