Custom Autosuggest API v7 リファレンスCustom Autosuggest API v7 reference

警告

Bing Search APIs は Cognitive Services から Bing Search サービスに移行しています。Bing Search APIs are moving from Cognitive Services to Bing Search Services. 2020 年10月 30 日以降、Bing Search の新しいインスタンスは、 ここに記載されている手順に従ってプロビジョニングする必要があります。Starting October 30, 2020 , any new instances of Bing Search need to be provisioned following the process documented here. Cognitive Services を使用してプロビジョニングされた Bing Search APIs は、次の3年間、またはマイクロソフトエンタープライズ契約の終わり (どちらか早い方) にサポートされます。Bing Search APIs provisioned using Cognitive Services will be supported for the next three years or until the end of your Enterprise Agreement, whichever happens first. 移行手順については、「 Bing Search Services」を参照してください。For migration instructions, see Bing Search Services.

Custom Autosuggest API を使用すると、部分的な検索クエリ文字列を Bing に送信し、提案されたクエリの一覧を取得できます。The Custom Autosuggest API lets you send a partial search query string to Bing and get back a list of suggested queries. 通常、この API を使用して、より高度な検索エクスペリエンスをサポートします。Typically, you use this API to support a richer search experience. たとえば、ユーザーが検索語の各文字を入力するときに、この API を呼び出して、検索ボックスのドロップダウン リストにクエリ文字列の候補を入力します。For example, as the user enters each character of their search term, you'd call this API and populate the search box's drop-down list with the suggested query strings.

カスタム候補の構成の詳細については、「 カスタム Autosuggest エクスペリエンスの構成」を参照してください。For information about configuring custom suggestions, see Configure your Custom Autosuggest experience.

要求に含めるヘッダーの詳細については、「 要求ヘッダー」を参照してください。For information about the headers that you should include in the request, see Request Headers.

要求に含める必要があるクエリパラメーターの詳細については、「 クエリパラメーター」を参照してください。For information about the query parameters that you should include in the request, see Query Parameters.

応答に含めることができる JSON オブジェクトの詳細については、「 応答オブジェクト」を参照してください。For information about the JSON objects that the response may include, see Response Objects.

結果の使用と表示の許可の詳細については、「 BING SEARCH API の使用と表示の要件」を参照してください。For information about permitted use and display of results, see Bing Search API Use and Display requirements.

注意

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.

エンドポイントEndpoint

カスタム クエリ候補を要求するには、GET 要求を次の URL へ送信します。To request custom query suggestions, send a GET request to:

https://api.cognitive.microsoft.com/bingcustomsearch/v7.0/suggestions/search

要求では、HTTPS プロトコルを使う必要があります。The request must use the HTTPS protocol.

注意

URL の最大長は 2,048 文字です。The maximum URL length is 2,048 characters. URL の長さが上限を超えないよう、クエリ パラメーターの最大長は 1,500 文字未満にする必要があります。To ensure that your URL length does not exceed the limit, the maximum length of your query parameters should be less than 1,500 characters. URL が 2,048 文字を超えた場合、サーバーが 404 Not found を返します。If the URL exceeds 2,048 characters, the server returns 404 Not found.

ヘッダーHeaders

要求と応答に含まれる可能性があるヘッダーを次に示します。The following are the headers that a request and response may include.

ヘッダーHeader 説明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 必須の要求ヘッダー。Required request header.

Cognitive Services でこのサービスにサインアップしたときに受け取ったサブスクリプション キーです。The subscription key that you received when you signed up for this service in Cognitive Services.
Retry-AfterRetry-After 応答ヘッダー。Response header.

応答には、1秒あたりに許可されるクエリの数 (QPS) または1か月 (QPM) を超える場合に、このヘッダーが含まれます。The response includes this header if you exceed the number of queries allowed per second (QPS) or per month (QPM). ヘッダーには、別の要求を送信する前に待機する必要がある秒数が含まれています。The header contains the number of seconds that you must wait before sending another request.

注意

利用規約ですべての該当法規 (これらのヘッダーの使用に関するものなど) への準拠が要求されていることに注意してください。Remember that the Terms of Use require compliance with all applicable laws, including regarding use of these headers. たとえば、ヨーロッパなどの特定の地域では、特定の追跡デバイスをユーザー デバイスに組み込む前に、ユーザーの同意を得る必要があります。For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.

クエリ パラメーターQuery parameters

要求に含めることができるクエリ パラメーターを次に示します。The following are the query parameters that the request may include. 必須列は、パラメーターを指定する必要があるかどうかを示します。The Required column indicates whether you must specify the parameter. クエリ パラメーターの値を URL エンコードする必要があります。You must URL encode the query parameter values.

NameName Value Type 必須Required
Customconfig.jsoncustomConfig カスタム検索インスタンスを識別する一意の識別子。Unique identifier that identifies your custom search instance.

StringString はいYes
qq ユーザーの検索クエリ文字列。The user's search query string.

クエリ文字列を空にすることはできません。The query string must not be empty. 空の場合、または指定されていない場合は、応答の候補の一覧が空になります。If empty or not specified, the list of suggestions in the response is empty.

この API では、 Bing Advanced Operatorsはサポートされていません。The API does not support the Bing Advanced Operators. クエリ文字列に Bing の演算子が含まれている場合、演算子は演算子としてではなく、クエリ文字列の一部として扱われます。If the query string includes Bing operators, the operators are treated as part of the query string, not as an operator.
StringString いいえNo

応答オブジェクトResponse objects

応答に含めることができる JSON オブジェクトを次に示します。The following are the JSON objects that the response may include. 要求が成功すると、応答の最上位レベルのオブジェクトが 候補 オブジェクトになります。If the request is successful, the top-level object in the response is the Suggestions object. 要求が失敗した場合、最上位レベルのオブジェクトは Errorresponseです。If the request fails, the top-level object is ErrorResponse.

ObjectObject 説明Description
ErrorError 発生したエラーを定義します。Defines the error that occurred.
ErrorResponseErrorResponse 要求が失敗したときの応答に含まれている最上位レベルのオブジェクト。The top-level object that the response includes when the request fails.
QueryContextQueryContext Bing が要求に使用したクエリ用語を定義します。Defines the query term that Bing used for the request.
SearchActionSearchAction 推奨される検索クエリを定義します。Defines the suggested search query.
SuggestionGroupSuggestionGroup 同じ種類の候補のグループを定義します。Defines a group of suggestions of the same type.
検索候補Suggestions 要求が成功したときに応答に含まれるトップレベルのオブジェクト。The top-level object that the response includes when the request succeeds.

エラーError

発生したエラーを定義します。Defines the error that occurred.

要素Element 説明Description TypeType
codecode エラーのカテゴリを特定するエラー コード。The error code that identifies the category of error. 考えられるコードの一覧については、「エラー コード」を参照してください。For a list of possible codes, see Error Codes. StringString
messagemessage エラーの説明。A description of the error. StringString
moreDetailsmoreDetails エラーに関する追加情報を提供する説明。A description that provides additional information about the error. StringString
parameterparameter エラーを引き起こした要求内のクエリ パラメーター。The query parameter in the request that caused the error. StringString
subCodesubCode エラーを特定するエラー コード。The error code that identifies the error. たとえば、code が InvalidRequest の場合、subCode は ParameterInvalid か ParameterInvalidValue の場合があります。For example, if code is InvalidRequest, subCode may be ParameterInvalid or ParameterInvalidValue. StringString
valuevalue 有効でなかったクエリ パラメーター値。The query parameter's value that was not valid. StringString

ErrorResponseErrorResponse

要求が失敗したときの応答に含まれている最上位レベルのオブジェクト。The top-level object that the response includes when the request fails.

名前Name Value TypeType
_type_type 種類のヒント。Type hint. StringString
errorserrors 要求が失敗した理由を示すエラーの一覧。A list of errors that describe the reasons why the request failed. Error[]Error[]

SearchActionSearchAction

クエリ検索候補を定義します。Defines a query search suggestion.

NameName Value Type
displayTextdisplayText ユーザーインターフェイスに表示するクエリ用語を提示します。The suggested query term to display in a user interface. StringString
queryquery 推奨されるクエリ用語。The suggested query term.

ユーザーが候補の一覧からクエリ用語を選択した場合は、Bing API 要求で用語を使用し、自分で検索結果を表示します。If the user selects the query term from the list of suggestions, use the term in a Bing API request and display the search results yourself. または、フィールドの URL を使用して、候補となる url クエリの Bing の [検索結果] ページにユーザーを送信します。Or, use the URL in the url field to send the user to the Bing search results page for the suggested query.
StringString
searchKindsearchKind 提案の種類。The type of suggestion. 有効な値を次に示します。The following are the possible values.
  • CustomSearch — 候補は、Web 検索候補以外のデータソースからのものです。CustomSearch—The suggestion is from a non-Web search suggestion data source.
  • Web 検索候補 — データソースからの提案を検索します。WebSearch—The suggestion is from a web search suggestion data source.
StringString

SuggestionGroupSuggestionGroup

同じ種類の候補のグループを定義します。Defines a group of suggestions of the same type.

NameName Value Type
指定name グループの名前。The name of the group. 名前は、グループに含まれる候補の種類を識別します。The name identifies the type of suggestions that the group contains. たとえば、web 検索候補です。For example, web search suggestions. 使用可能なグループ名を次に示します。The following are the possible group names.
  • カスタム — グループには、web 検索候補以外のデータソースからの提案が含まれています。Custom—The group contains suggestions from a non-web search suggestions data source.
  • Web — グループに web 検索の候補が含まれています。Web—The group contains web search suggestions.
StringString
searchSuggestionssearchSuggestions 最大8個の候補の一覧。A list of up to 8 suggestions. 候補がない場合、配列は空になります。If there are no suggestions, the array is empty.

指定された順序ですべての候補を表示する必要があります。You must display all suggestions in the order provided. この一覧は、関連性を下げるためのものです。The list is in order of decreasing relevance. 最初の提案は最も関連性が高く、最後の提案は最も関連性の低いものです。The first suggestion is the most relevant and the last suggestion is the least relevant. リストのサイズは変更される可能性があります。The size of the list is subject to change.
Searchaction[]SearchAction[]

検索候補Suggestions

要求が成功したときに応答に含まれるトップレベルのオブジェクト。The top-level object that the response includes when the request succeeds.

サービスがサービス拒否攻撃を受けた場合、要求は成功します (HTTP 状態コードは 200 OK)。If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK). しかし、応答の本文は空になります。However, the body of the response is empty.

NameName Value TypeType
_type_type 型ヒント。候補に設定されています。The type hint, which is set to Suggestions. StringString
queryContextqueryContext ユーザーのクエリ文字列。The user's query string. QueryContextQueryContext
suggestionGroupssuggestionGroups 型別にグループ化された、推奨されるクエリ文字列の一覧。A list of suggested query strings grouped by type. たとえば、web 検索候補です。For example, web search suggestions. SuggestionGroup[]SuggestionGroup[]

エラー コードError codes

要求によって返される可能性のある HTTP 状態コードを次に示します。The following are the possible HTTP status codes that a request returns.

状態コードStatus Code 説明Description
200200 正常終了しました。Success.
400400 クエリ パラメーターの 1 つが欠落しているか無効です。One of the query parameters is missing or not valid.
401401 サブスクリプション キーが見つからないか、無効です。The subscription key is missing or is not valid.
410410 HTTPS プロトコルではなく HTTP プロトコルが使用された要求。The request used HTTP instead of the HTTPS protocol. サポートされるプロトコルは HTTPS のみです。HTTPS is the only supported protocol.
429429 呼び出し元が 1 秒あたりのクエリ数のクォータを超えました。The caller exceeded their queries per second quota.
500500 予期しないサーバー エラー。Unexpected server error.

要求が失敗すると、応答に ErrorResponse オブジェクトが含まれます。このオブジェクトには、エラーの原因を示す Error オブジェクトの一覧が含まれています。If the request fails, the response contains an ErrorResponse object, which contains a list of Error objects that describe what caused of error. エラーがパラメーターに関連している場合、parameter フィールドで、問題であるパラメーターが特定されます。If the error is related to a parameter, the parameter field identifies the parameter that is the issue. エラーがパラメーター値に関連している場合、value フィールドで、無効な値が特定されます。And if the error is related to a parameter value, the value field identifies the value that is not valid.

{
  "_type": "ErrorResponse", 
  "errors": [
    {
      "code": "InvalidRequest", 
      "subCode": "ParameterMissing", 
      "message": "Required parameter is missing.", 
      "parameter": "q" 
    }
  ]
}

{
  "_type": "ErrorResponse", 
  "errors": [
    {
      "code": "InvalidAuthorization", 
      "subCode": "AuthorizationMissing", 
      "message": "Authorization is required.", 
      "moreDetails": "Subscription key is not recognized."
    }
  ]
}

考えられるエラー コードとサブエラー コードの値を次に示します。The following are the possible error code and sub-error code values.

コードCode サブコードSubCode 説明Description
ServerErrorServerError UnexpectedErrorUnexpectedError
ResourceErrorResourceError
NotImplementedNotImplemented
HTTP 状態コードは 500 です。HTTP status code is 500.
InvalidRequestInvalidRequest ParameterMissingParameterMissing
ParameterInvalidValueParameterInvalidValue
HttpNotAllowedHttpNotAllowed
BlockedBlocked
要求の一部が有効でない場合に Bing は InvalidRequest を返します。Bing returns InvalidRequest whenever any part of the request is not valid. たとえば、必要なパラメーターが不足している場合や、パラメーター値が無効な場合です。For example, a required parameter is missing or a parameter value is not valid.

エラーが ParameterMissing または ParameterInvalidValue の場合、HTTP 状態コードは 400 です。If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400.

HTTPS プロトコルではなく HTTP プロトコルを使用すると、Bing は HttpNotAllowed を返し、HTTP 状態コードは 410 になります。If you use the HTTP protocol instead of HTTPS, Bing returns HttpNotAllowed, and the HTTP status code is 410.
RateLimitExceededRateLimitExceeded No sub-codesNo sub-codes 1 秒あたりのクエリ数 (QPS) または 1 か月あたりのクエリ数 (QPM) のクォータを超えると、Bing は RateLimitExceeded を返します。Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.

QPS を超えた場合、Bing は HTTP 状態コード 429 を返します。また、QPM を超えた場合、Bing は 403 を返します。If you exceed QPS, Bing returns HTTP status code 429, and if you exceed QPM, Bing returns 403.
InvalidAuthorizationInvalidAuthorization AuthorizationMissingAuthorizationMissing
AuthorizationRedundancyAuthorizationRedundancy
Bing は、呼び出し元を認証できない場合に InvalidAuthorization を返します。Bing returns InvalidAuthorization when Bing cannot authenticate the caller. たとえば、Ocp-Apim-Subscription-Key ヘッダーがない場合や、サブスクリプション キーが無効な場合です。For example, the Ocp-Apim-Subscription-Key header is missing or the subscription key is not valid.

冗長性は、複数の認証方法を指定した場合に発生します。Redundancy occurs if you specify more than one authentication method.

エラーが InvalidAuthorization の場合、HTTP 状態コードは 401 です。If the error is InvalidAuthorization, the HTTP status code is 401.
NoSuggestionsNoSuggestions No sub-codesNo sub-codes 提案が見つかりませんでした。 HTTP 状態コードは404です。No suggestions found, the HTTP status code is 404.