Bing Autosuggest API への要求の送信
警告
2020 年 10 月 30 日に、Bing Search API は Azure AI サービスから Bing Search サービスに移行されました。 このドキュメントは、参考用としてのみ提供されています。 更新されたドキュメントについては、Bing search API のドキュメントを参照してください。 Bing 検索用の新しい Azure リソースを作成する手順については、「Azure Marketplace から Bing Search リソースを作成する」を参照してください。
アプリケーションから Bing Search API のいずれかにクエリを送信する場合、ユーザーの検索エクスペリエンスを向上させるために Bing Autosuggest API を使用することができます。 Bing Autosuggest API は、検索ボックス内の部分的なクエリ文字列に基づいて、候補となるクエリの一覧を返します。 アプリケーションの検索ボックスに文字が入力されると、ドロップダウン リスト内に候補を表示できます。 この記事を使用して、この API への要求の送信について確認してください。
Bing Autosuggest API のエンドポイント
Bing Autosuggest API には、検索用語の一部から取得されたクエリ候補の一覧を返す 1 つのエンドポイントが含まれています。
Bing API を使用してクエリ候補を取得するには、次のエンドポイントに GET 要求を送信します。 ヘッダーと URL パラメーターを使用して、さらに詳細を定義します。
エンドポイント: 検索候補を、?q="" によって定義されたユーザーの入力に関連する JSON 結果として返します。
GET https://api.cognitive.microsoft.com/bing/v7.0/Suggestions
ヘッダー、パラメーター、市場コード、応答オブジェクト、エラーなどについて詳しくは、Bing Autosuggest API v7 のリファレンスをご覧ください。
Bing API では、種類に応じた結果を返す検索アクションがサポートされます。 すべての検索エンドポイントは、結果を JSON 応答オブジェクトとして返します。 すべてのエンドポイントは、特定の言語や場所を経度、緯度、検索半径によって返すクエリをサポートします。
各エンドポイントでサポートされるパラメーターについて詳しくは、各種類のリファレンス ページをご覧ください。 Autosuggest API を使用した基本的な要求の例については、Autosuggest のクイック スタートをご覧ください。
Bing Autosuggest API の要求
Note
- Bing Autosuggest API への要求には、HTTPS プロトコルを使用する必要があります。
すべての要求をサーバーから送信することをお勧めします。 クライアント アプリケーションの一部としてキーを配布すると、悪意のあるサードパーティがアクセスする可能性が高くなります。 また、サーバーから呼び出しを行うと、今後の更新プログラムにアップグレードする場所が 1 つで済みます。
要求では、ユーザーの部分検索語句が含まれている q クエリ パラメーターを指定する必要があります。 必須ではありませんが、要求では mkt クエリ パラメーターも指定するべきです。このパラメーターは、結果取得元の市場を示します。 省略可能なクエリ パラメーターの一覧については、「Query Parameters (クエリ パラメーター)」を参照してください。 すべてのクエリ パラメーターの値は、URL でエンコードする必要があります。
要求では、Ocp-Apim-Subscription-Key ヘッダーを指定する必要があります。 省略可能ですが、次のヘッダーも指定することをお勧めします。
クライアント IP と場所のヘッダーは、場所に対応したコンテンツを返すために重要です。
すべての要求ヘッダーと応答ヘッダーのリストについては、「Headers」(ヘッダー) を参照してください。
Note
JavaScript から Bing Autosuggest API を呼び出すときに、ブラウザーの組み込みのセキュリティ機能によっては、これらのヘッダーの値にアクセスできない場合があります。
これを解決するため、CORS プロキシを介して Bing Autosuggest API 要求を作成することができます。 そのようなプロキシからの応答には、応答ヘッダーをフィルター処理して JavaScript で使用できるようにする Access-Control-Expose-Headers ヘッダーが含まれています。
CORS プロキシをインストールしてチュートリアル アプリが省略可能なクライアント ヘッダーにアクセスできるようにするのは簡単です。 まず、Node.js をインストールします (まだインストールしていない場合)。 その後、コマンド プロンプトで次のコマンドを入力します。
npm install -g cors-proxy-server
次に、HTML ファイル内の Bing Autosuggest API エンドポイントを次のように変更します。
http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/Suggestions
最後に、次のコマンドを使用して、CORS プロキシを開始します。
cors-proxy-server
チュートリアル アプリを使用している間はコマンド ウィンドウを開いたままにしておいてください。ウィンドウを閉じるとプロキシが停止します。 検索結果の下の展開可能な HTTP ヘッダー セクションに、X-MSEdge-ClientID ヘッダー (など) が表示され、各要求で同じであることを確認できます。
要求には、推奨されるすべてのクエリ パラメーターとヘッダーが含まれている必要があります。
次の例に、sail に対するクエリ文字列の候補を返す要求を示します。
GET https://api.cognitive.microsoft.com/bing/v7.0/suggestions?q=sail&mkt=en-us HTTP/1.1 Ocp-Apim-Subscription-Key: 123456789ABCDE X-MSEdge-ClientIP: 999.999.999.999 X-Search-Location: lat:47.60357;long:-122.3295;re:100 X-MSEdge-ClientID: <blobFromPriorResponseGoesHere> Host: api.cognitive.microsoft.com
いずれかの Bing API を初めて呼び出す場合は、クライアント ID ヘッダーを含めないでください。 クライアント ID ヘッダーを含めるのは、過去に Bing API を呼び出したことがあり、かつユーザーとデバイスの組み合わせに対応するクライアント ID が Bing から返されたことがある場合だけです。
次の Web 候補グループは、上の要求に対する応答です。 このグループには、検索クエリ候補の一覧が含まれています。各候補には、displayText、query、および url フィールドが含まれています。
displayText フィールドには、検索ボックスのドロップダウン リストの設定に使用するクエリ候補が含まれています。 応答に含まれるすべての候補を、指定された順序で表示する必要があります。
ユーザーがドロップダウン リストからクエリを選択すると、それを使用して Bing Search API の 1 つを呼び出して自身の結果を表示したり、返された url フィールドを使用して Bing 結果ページにそのユーザーを送信したりできます。
Note
URL の書式とパラメーターは、予告なしで変更されることがあるため、すべての URL をそのまま使用してください。 明記されている場合を除いて、URL の書式またはパラメーターに依存しないでください。
BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US
{
"_type" : "Suggestions",
"queryContext" : {
"originalQuery" : "sail"
},
"suggestionGroups" : [{
"name" : "Web",
"searchSuggestions" : [{
"url" : "https:\/\/www.bing.com\/search?q=sailing+lessons+seattle&FORM=USBAPI",
"displayText" : "sailing lessons seattle",
"query" : "sailing lessons seattle",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailor+moon+news&FORM=USBAPI",
"displayText" : "sailor moon news",
"query" : "sailor moon news",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailor+jack%27s+lincoln+city&FORM=USBAPI",
"displayText" : "sailor jack's lincoln city",
"query" : "sailor jack's lincoln city",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailing+anarchy&FORM=USBAPI",
"displayText" : "sailing anarchy",
"query" : "sailing anarchy",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale&FORM=USBAPI",
"displayText" : "sailboats for sale",
"query" : "sailboats for sale",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailstn.mylabsplus.com&FORM=USBAPI",
"displayText" : "sailstn.mylabsplus.com",
"query" : "sailstn.mylabsplus.com",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailusfood&FORM=USBAPI",
"displayText" : "sailusfood",
"query" : "sailusfood",
"searchKind" : "WebSearch"
},
{
"url" : "https:\/\/www.bing.com\/search?q=sailboats+for+sale+seattle&FORM=USBAPI",
"displayText" : "sailboats for sale seattle",
"query" : "sailboats for sale seattle",
"searchKind" : "WebSearch"
}]
}]
}