次の方法で共有


Windows Search Web 検索プロバイダー

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

Windows Search UI とサード パーティの検索プロバイダーの統合のスクリーンショット。

検索プロバイダーは、検索プロバイダーを登録するために 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リクエストとクロスオリジンリソースシェアリング (CORS)

検索プロバイダーは 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 フレーム内にある必要があります。

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