自訂自動建議 API v7 參考Custom Autosuggest API v7 reference

自訂自動建議 API 允許您將部分搜索查詢字串發送到必應,並返回建議查詢的清單。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.

有關配置自訂建議的資訊,請參閱配置自訂自動建議體驗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.

有關允許使用和顯示結果的資訊,請參閱必應搜索 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 要求傳送至: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 找不到」。If the URL exceeds 2,048 characters, the server returns 404 Not found.

headersHeaders

以下是要求和回應可能包含的標頭。The following are the headers that a request and response may include.

頁首Header 描述Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 必要的要求標頭。Required request header.

您在認知服務中註冊此服務時收到的訂用帳戶金鑰。The subscription key that you received when you signed up for this service in Cognitive Services.
重試後Retry-After 回應標頭。Response header.

如果超過每秒 (QPS) 或每月 (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. [必要] 欄l指出您是否必須定該參數。The Required column indicates whether you must specify the parameter. 您必須為查詢參數值進行 URL 編碼。You must URL encode the query parameter values.

名稱Name Value 類型Type 必要Required
自訂配置customConfig 標識自訂搜索實例的唯一識別碼。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 不支援必應高級運算子The API does not support the Bing Advanced Operators. 如果查詢字串包括必應運算子,則運算子將被視為查詢字串的一部分,而不是運算子。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. 如果請求失敗,頂級物件為錯誤回應If the request fails, the top-level object is ErrorResponse.

ObjectObject 描述Description
錯誤Error 定義發生的錯誤。Defines the error that occurred.
ErrorResponseErrorResponse 要求失敗時,回應包含的最上層物件。The top-level object that the response includes when the request fails.
QueryContextQueryContext 定義必應用於請求的查詢術語。Defines the query term that Bing used for the request.
搜索操作SearchAction 定義建議的搜索查詢。Defines the suggested search query.
建議組SuggestionGroup 定義一組相同類型的建議。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 類型Type
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 類型Type
_type_type 類型提示。Type hint. StringString
errorserrors 說明要求失敗原因的錯誤清單。A list of errors that describe the reasons why the request failed. 錯誤 Error[]

搜索操作SearchAction

定義查詢搜索建議。Defines a query search suggestion.

名稱Name Value 類型Type
displayTextdisplayText 要在使用者介面中顯示的建議查詢術語。The suggested query term to display in a user interface. StringString
查詢query 建議的查詢術語。The suggested query term.

如果使用者從建議清單中選取查詢術語,請在必應 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. 或者,使用欄位中的urlURL 將使用者發送到 Bing 搜尋結果頁以查找建議的查詢。Or, use the URL in the url field to send the user to the Bing search results page for the suggested query.
StringString
搜索金德searchKind 建議的類型。The type of suggestion. 以下是可能的值。The following are the possible values.
  • 自訂搜索—該建議來自非 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

建議組SuggestionGroup

定義一組相同類型的建議。Defines a group of suggestions of the same type.

名稱Name 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—The group contains web search suggestions.
StringString
搜索建議searchSuggestions 最多 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[]

建議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.

名稱Name Value 類型Type
_type_type 類型提示,設置為"建議"。The type hint, which is set to Suggestions. StringString
queryContextqueryContext 使用者的查詢字串。The user's query string. QueryContextQueryContext
建議組suggestionGroups 按類型分組的建議查詢字串的清單。A list of suggested query strings grouped by type. 例如,Web 搜索建議。For example, web search suggestions. 建議組 SuggestionGroup[]

錯誤碼Error codes

以下是要求傳回的可能 HTTP 狀態碼。The following are the possible HTTP status codes that a request returns.

狀態碼Status Code 描述Description
200200 成功。Success.
400400 缺少其中一個查詢參數,或查詢參數無效。One of the query parameters is missing or not valid.
401401 缺少訂用帳戶金鑰或無效。The subscription key is missing or is not valid.
410410 要求所用的是 HTTP 而非 HTTPS 通訊協定。The request used HTTP instead of the HTTPS protocol. HTTPS 是唯一支援的通訊協定。HTTPS is the only supported protocol.
429429 呼叫者超過其每秒查詢配額。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.

如果您使用的是 HTTP 通訊協定,而不是 HTTPS,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-codes 每當您超過每秒查詢 (QPS) 或每月查詢 (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 無法驗證呼叫者時,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.
無建議NoSuggestions 沒有子代碼No sub-codes 未找到建議,HTTP 狀態碼為 404。No suggestions found, the HTTP status code is 404.