Windows Search プロバイダー

  • [アーティクル]

Note

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

重要

このトピックで説明する機能は、Windows のプレビュー ビルドで使用できます。 Windows のプレビュー ビルドについては、「Windows 10 Insider プレビュー」を参照してください。

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

Screenshot of the Windows Search UI with 3rd party search provider integration.

検索プロバイダーは、検索プロバイダーを登録するために OS に必要な情報を提供するパッケージ マニフェスト ファイルを使用して MSIX パッケージを作成することで、Search エクスペリエンスと統合されます。 ユーザーは、Microsoft Store から関連付けられているアプリ パッケージをインストールして 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」を参照してください。

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

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>
		  </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 要求とクロスオリジン リソース共有 (CORS)

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