Bing Autosuggest API への要求の送信Sending requests to the Bing Autosuggest API.

アプリケーションから Bing Search API のいずれかにクエリを送信する場合、ユーザーの検索エクスペリエンスを向上させるために Bing Autosuggest API を使用することができます。If your application sends queries to any of the Bing Search APIs, you can use the Bing Autosuggest API to improve your users' search experience. Bing Autosuggest API は、検索ボックス内の部分的なクエリ文字列に基づいて、候補となるクエリの一覧を返します。The Bing Autosuggest API returns a list of suggested queries based on the partial query string in the search box. アプリケーションの検索ボックスに文字が入力されると、ドロップダウン リスト内に候補を表示できます。As characters are entered into a search box in your application, you can display suggestions in a drop-down list. この記事を使用して、この API への要求の送信について確認してください。Use this article to learn more about sending requests to this API.

Bing Autosuggest API のエンドポイントBing Autosuggest API Endpoint

Bing Autosuggest API には、検索用語の一部から取得されたクエリ候補の一覧を返す 1 つのエンドポイントが含まれています。The Bing Autosuggest API includes one endpoint, which returns a list of suggested queries from a partial search term.

Bing API を使用してクエリ候補を取得するには、次のエンドポイントに GET 要求を送信します。To get suggested queries using the Bing API, send a GET request to the following endpoint. ヘッダーと URL パラメーターを使用して、さらに詳細を定義します。Use the headers and URL parameters to define further specifications.

エンドポイント: 検索候補を、?q="" によって定義されたユーザーの入力に関連する JSON 結果として返します。Endpoint: Returns search suggestions as JSON results that are relevant to the user's input defined by ?q="".

GET https://api.cognitive.microsoft.com/bing/v7.0/Suggestions 

ヘッダー、パラメーター、市場コード、応答オブジェクト、エラーなどについて詳しくは、Bing Autosuggest API v7 のリファレンスをご覧ください。For details about headers, parameters, market codes, response objects, errors, etc., see the Bing Autosuggest API v7 reference.

Bing API では、種類に応じた結果を返す検索アクションがサポートされます。The Bing APIs support search actions that return results according to their type. すべての検索エンドポイントは、結果を JSON 応答オブジェクトとして返します。 All search endpoints return results as JSON response objects. すべてのエンドポイントは、特定の言語や場所を経度、緯度、検索半径によって返すクエリをサポートします。All endpoints support queries that return a specific language and/or location by longitude, latitude, and search radius.

各エンドポイントでサポートされるパラメーターについて詳しくは、各種類のリファレンス ページをご覧ください。For complete information about the parameters supported by each endpoint, see the reference pages for each type. Autosuggest API を使用した基本的な要求の例については、Autosuggest のクイック スタートをご覧ください。For examples of basic requests using the Autosuggest API, see Autosuggest Quickstarts.

Bing Autosuggest API の要求Bing Autosuggest API requests

注意

  • Bing Autosuggest API への要求には、HTTPS プロトコルを使用する必要があります。Requests to the Bing Autosuggest API must use the HTTPS protocol.

すべての要求をサーバーから送信することをお勧めします。We recommend that all requests originate from a server. クライアント アプリケーションの一部としてキーを配布すると、悪意のあるサードパーティがアクセスする可能性が高くなります。Distributing the key as part of a client application provides more opportunity malicious third-party access. また、サーバーから呼び出しを行うと、今後の更新プログラムにアップグレードする場所が 1 つで済みます。Additionally, making calls from a server provides a single upgrade point for future updates.

要求では、ユーザーの部分検索語句が含まれている q クエリ パラメーターを指定する必要があります。The request must specify the q query parameter, which contains the user's partial search term. 必須ではありませんが、要求では mkt クエリ パラメーターも指定するべきです。このパラメーターは、結果取得元の市場を示します。Although it's optional, the request should also specify the mkt query parameter, which identifies the market where you want the results to come from. 省略可能なクエリ パラメーターの一覧については、「Query Parameters (クエリ パラメーター)」を参照してください。For a list of optional query parameters, see Query Parameters. すべてのクエリ パラメーターの値は、URL でエンコードする必要があります。All query parameter values must be URL encoded.

要求では、Ocp-Apim-Subscription-Key ヘッダーを指定する必要があります。The request must specify the Ocp-Apim-Subscription-Key header. 省略可能ですが、次のヘッダーも指定することをお勧めします。Although optional, you are encouraged to also specify the following headers:

クライアント IP と場所のヘッダーは、場所に対応したコンテンツを返すために重要です。The client IP and location headers are important for returning location aware content.

すべての要求ヘッダーと応答ヘッダーのリストについては、「Headers」(ヘッダー) を参照してください。For a list of all request and response headers, see Headers.

注意

JavaScript から Bing Autosuggest API を呼び出すときに、ブラウザーの組み込みのセキュリティ機能によっては、これらのヘッダーの値にアクセスできない場合があります。When you call the Bing Autosuggest API from JavaScript, your browser's built-in security features might prevent you from accessing the values of these headers.

これを解決するため、CORS プロキシを介して Bing Autosuggest API 要求を作成することができます。To resolve this, you can make the Bing Autosuggest API request through a CORS proxy. このようなプロキシからの応答には、応答ヘッダーをホワイトリストに登録し、それらを JavaScript で使用できるようにする Access-Control-Expose-Headers ヘッダーがあります。The response from such a proxy has a Access-Control-Expose-Headers header that whitelists response headers and makes them available to JavaScript.

CORS プロキシをインストールしてチュートリアル アプリが省略可能なクライアント ヘッダーにアクセスできるようにするのは簡単です。It's easy to install a CORS proxy to allow our tutorial app to access the optional client headers. まず、Node.js をインストールします (まだインストールしていない場合)。First, if you don't already have it, install Node.js. その後、コマンド プロンプトで次のコマンドを入力します。Then enter the following command at a command prompt.

npm install -g cors-proxy-server

次に、HTML ファイル内の Bing Autosuggest API エンドポイントを次のように変更します。Next, change the Bing Autosuggest API endpoint in the HTML file to:

http://localhost:9090/https://api.cognitive.microsoft.com/bing/v7.0/Suggestions

最後に、次のコマンドを使用して、CORS プロキシを開始します。Finally, start the CORS proxy with the following command:

cors-proxy-server

チュートリアル アプリを使用している間はコマンド ウィンドウを開いたままにしておいてください。ウィンドウを閉じるとプロキシが停止します。Leave the command window open while you use the tutorial app; closing the window stops the proxy. 検索結果の下の展開可能な HTTP ヘッダー セクションに、X-MSEdge-ClientID ヘッダー (など) が表示され、各要求で同じであることを確認できます。In the expandable HTTP Headers section below the search results, you can now see the X-MSEdge-ClientID header (among others) and verify that it is the same for each request.

要求には、推奨されるすべてのクエリ パラメーターとヘッダーが含まれている必要があります。Requests should include all suggested query parameters and headers.

次の例に、sail に対するクエリ文字列の候補を返す要求を示します。The following example shows a request that returns the suggested query strings for 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 ヘッダーを含めないでください。If it's your first time calling any of the Bing APIs, don't include the client ID header. クライアント ID ヘッダーを含めるのは、過去に Bing API を呼び出したことがあり、かつユーザーとデバイスの組み合わせに対応するクライアント ID が Bing から返されたことがある場合だけです。Only include the client ID header if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

次の Web 候補グループは、上の要求に対する応答です。The following web suggestion group is a response to the above request. このグループには、検索クエリ候補の一覧が含まれています。各候補には、displayTextquery、および url フィールドが含まれています。The group contains a list of search query suggestions, with each suggestion including a displayText, query, and url field.

displayText フィールドには、検索ボックスのドロップダウン リストの設定に使用するクエリ候補が含まれています。The displayText field contains the suggested query that you'd use to populate your search box's drop-down list. 応答に含まれるすべての候補を、指定された順序で表示する必要があります。You must display all suggestions that the response includes, and in the given order.

ユーザーがドロップダウン リストからクエリを選択すると、それを使用して Bing Search API の 1 つを呼び出して自身の結果を表示したり、返された url フィールドを使用して Bing 結果ページにそのユーザーを送信したりできます。If the user selects a query from the drop-down list, you can use it to call the one of the Bing Search APIs and display the results yourself, or send the user to the Bing results page using the returned url field.

注意

URL の書式とパラメーターは、予告なしで変更されることがあるため、すべての URL をそのまま使用してください。Because URL formats and parameters are subject to change without notice, use all URLs as-is. 明記されている場合を除いて、URL の書式またはパラメーターに依存しないでください。You should not take dependencies on the URL format or parameters except where noted.

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"
        }]
    }]
}

次のステップNext steps