你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

自动建议 API v7 参考

警告

必应搜索 API 将从认知服务迁移到必应搜索服务。 从 2020 年 10 月 30 日开始,必应搜索的任何新实例都需按照此处所述的过程进行预配。 使用认知服务进行预配的必应搜索 API 将在未来三年或在企业协议结束前(以先发生者为准)得到支持。 有关迁移说明,请参阅必应搜索服务

使用自动建议 API 可以发送部分搜索查询词以必应并返回其他用户搜索的建议查询列表。 除了包括其他人进行的搜索外,该列表还可能包含基于用户意向的建议。

通常,使用此 API 支持更丰富的搜索框体验。 例如,当用户输入其搜索词的每个字符时,便会调用此 API 并使用建议的查询字符串填充搜索框的下拉列表。

本部分提供有关请求可能包含的查询参数和标头以及包含建议查询的 JSON 响应的技术详细信息。 有关如何发出请求的示例,请参阅 “获取建议的搜索词”。

有关应包含在请求中的标头的信息,请参阅 “请求标头”。

有关应包含在请求中的查询参数的信息,请参阅 查询参数

有关响应可能包含的 JSON 对象的信息,请参阅 响应对象

有关允许使用和显示结果的信息,请参阅必应搜索 API 使用和显示要求

注意

由于 URL 格式和参数可能会在未另行通知的情况下有所更改,请按现状使用所有 URL。 不应依赖于 URL 格式或参数,除非另有说明。

终结点

若要请求查询建议,请将 GET 请求发送到:

https://api.cognitive.microsoft.com/bing/v7.0/suggestions

对于多服务订阅,必须在 URL 中包含该区域。 例如:westus.api.cognitive.microsoft.com。 请参阅支持的区域

请求必须使用 HTTPS 协议。

注意

最大 URL 长度为 2,048 个字符。 为了确保 URL 长度不超出限制,查询参数的最大长度应不到 1,500 个字符。 如果 URL 超出 2,048 个字符,服务器会返回“404 未找到”。

标头

下面是请求和响应可能包含的标头。

标头 说明
Accept 可选请求标头。

默认的媒体类型为“application/json”。 若要指定响应使用 JSON-LD,请将 Accept 标头设置为“application/ld+json”。
Accept-Language 可选请求标头。

以逗号分隔的语言列表,用于用户界面字符串。 此列表以降序方式显示首选项。 有关详细信息,包括预期格式,请参阅 RFC2616

此标头和 setLang 查询参数相互排斥,不可同时指定两者。

如果设置此标头,则还必须指定 cc 查询参数。 为了确定针对哪个市场返回结果,必应使用从列表中找到的第一个受支持语言并将其与 cc 参数值相结合。 如果列表不包括支持的语言,必应会查找最接近的语言和支持请求的市场,或将聚合或默认市场用于结果。 若要确定必应使用的市场,请查看 BingAPIs-Market 标头。

仅当指定多个语言时,才可使用此标头和 cc 查询参数。 否则,请使用 mktsetLang 查询参数。

用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。 响应对象中 Bing.com 属性的任何链接均将应用指定的语言。
BingAPIs-Market 响应标头。

请求使用的市场。 形式为 <languageCode>-<countryCode>。 例如,en-US。

如果指定市场 代码中未列出的市场,此值可能与 mkt 查询参数中指定的市场不同。 如果为 无法协调的 ccAccept-Language 指定值,则也是如此。
BingAPIs-TraceId 响应标头。

包含请求详细信息的日志条目 ID。 发生错误时,捕获此 ID。 如果无法确定并解决问题,请纳入此 ID 以及提供给支持团队的其他信息。
Ocp-Apim-Subscription-Key 必需请求标头。

认知服务中注册此服务时收到的订阅密钥。
Pragma 可选请求标头

默认情况下,必应返回缓存的内容(如果适用)。 若要防止缓存内容,请将 Pragma 标头设置为 no-cache (,例如 Pragma:no-cache) 。
Retry-After 响应标头。

如果超出 QPS) 或每月 ( (QPM) 允许的查询数,则响应将包含此标头。 标头包含在发送另一个请求之前必须等待的秒数。
User-Agent 可选请求标头。

发出请求的用户代理。 必应使用用户代理为移动用户提供优化体验。 尽管是可选的,但还是建议始终指定此标头。

user-agent 应该是任何常用浏览器发送的字符串。 有关用户代理的信息,请参阅 RFC 2616

下面是 user-agent 字符串示例。
  • Windows Phone - Mozilla/5.0(兼容;MSIE 10.0;Windows Phone 8.0;Trident/6.0;IEMobile/10.0;ARM;Touch;NOKIA;Lumia 822)

  • Android - Mozilla/5.0(Linux;U;Android 2.3.5;en-us;SCH-I500 Build/GINGERBREAD)AppleWebKit/533.1(KHTML,如 Gecko)版本/4.0 Mobile Safari/533.1

  • iPhone - Mozilla/5.0(iPhone;CPU iPhone OS 6_1,如 Mac OS X)AppleWebKit/536.26(KHTML;如 Gecko)Mobile/10B142 iPhone4;1 BingWeb/3.03.1428.20120423

  • PC - Mozilla/5.0(Windows NT 6.3;WOW64;Trident/7.0;Touch;rv:11.0),如 Gecko

  • iPad - Mozilla/5.0(iPad;CPU OS 7_0,如 Mac OS X)AppleWebKit/537.51.1(KHTML,如 Gecko)版本/7.0 Mobile/11A465 Safari/9537.53
X-MSEdge-ClientID 可选请求和响应标头。

必应使用此标头跨必应 API 调用为用户提供一致的行为。 必应通常会发布新功能和改进,并将客户端 ID 用作密钥以在不同航班上分配客流量。 如果未跨多个请求将相同的客户端 ID 用于用户,则必应可能将用户分配给多个冲突的航班。 分配给多个冲突航班可能导致用户体验不一致。 例如,如果第二个请求与第一个请求的航班分配不同,体验可能会出现意外。 此外,必应可以使用客户端 ID 为该客户端 ID 的搜索历史记录定制 Web 结果,从而为用户提供更丰富的体验。

通过分析由客户端 ID 生成的活动,必应还会使用此标头来提高结果排名。 相关改进有助于提高必应 API 交付的结果质量,从而提高 API 客户的点击率。

重要提示:尽管是可选的,但应将此标头视为必选。 对于同一最终用户和设备组合,如果跨多个请求保留客户端 ID,则 1) API 客户可以获取一致的用户体验;2) 可通过必应 API 提高结果质量,从而提高点击率。

下面是适用于此标头的基本用法规则。
  • 在设备上使用你的应用程序的每个用户必须具有必应生成的唯一客户端 ID。

    如果未在请求中包含此标头,必应会生成 ID,然后在 X-MSEdge-ClientID 响应标头中将其返回。 仅当用户首次在设备上使用应用时,才不可以在请求中包含此标头。

  • 针对应用为设备上的此用户生成的每个必应 API 请求,使用客户端 ID。

  • 注意:必须确保此客户端 ID 不能链接到任何可以进行身份验证的用户帐户信息。

  • 保留客户端 ID。 若要在浏览器应用中保留 ID,请使用持久性 HTTP Cookie 来确保所有会话均使用此 ID。 请勿使用会话 Cookie。 对于移动应用等其他应用,请使用设备的持久存储来保留 ID。

    下次用户在该设备上使用你的应用时,会获取保留的客户端 ID。

注意:必应响应不一定包含此标头。 如果响应包含此标头,请针对该设备上的用户捕获客户端 ID 并将其用于所有后续必应请求。

注意:如果包含 X-MSEdge-ClientID,不可在请求中包含 Cookie。
X-MSEdge-ClientIP 可选请求标头。

客户端设备的 IPv4 或 IPv6 地址。 IP 地址用于发现用户的位置。 必应使用位置信息来确定安全搜索行为。

注意:尽管是可选的,但还是建议始终指定此标头和 X-Search-Location 标头。

不要混淆地址(例如,通过将最后一个八位字节更改为 0 来混淆地址)。 混淆地址会导致位置未处于设备实际位置附近,这可能导致必应提供错误的结果。
X-Search-Location 可选请求标头。

以分号分隔的键/值对列表,描述客户端的地理位置。 必应使用位置信息来确定安全搜索行为并返回相关的本地内容。 以 <键>:<值> 形式指定键/值对。 下面是用于指定用户位置的键。

  • lat - 必需。 客户位置的纬度,以度为单位。 纬度必须大于或等于 -90.0 且小于或等于 +90.0。 负值表示南纬,正值表示北纬。

  • long - 必需。 客户位置的经度,以度为单位。 经度必须大于或等于 -180.0 且小于或等于 +180.0。 负值表示西经,正值表示东经。

  • re - 必需。 半径(以米为单位),指定坐标的水平准确性。 传递设备定位服务返回的值。 典型的值可能是:22m - GPS/Wi-Fi、380m - 蜂窝基站三角网定位、18,000m - 反向 IP 查询。

  • ts - 可选。 客户位于相应位置时的 UTC UNIX 时间戳。 (UNIX 时间戳是自 1970 年 1 月 1 日起的秒数。)

  • head - 可选。 客户端的相对航向或旅行方向。 以度数指定旅行方向(从 0 到 360),相对于正北方向顺时针计数。 如果 sp 键为非零值,则指定此键。

  • sp - 可选。 客户设备移动的水平速度(速度),以米/秒为单位。

  • alt - 可选。 客户设备的高度,以米为单位。

  • are - 可选。 半径(以米为单位),指定坐标的垂直准确度。 只有在指定 alt 键的情况下才指定此键。

  • disp - 可选。 用户的地理位置,格式为 disp:<City,State>。 例如,disp:Seattle、Washington。 这是使用 lat/long 键指定的用户位置的显示文本版本。 如果此值与 lat/long 坐标冲突,必应将 disp 值用作用户的位置。

注意:如果查询包含位置,必应将忽略此标头。 例如,如果此标头反映用户作为旧金山的位置,但查询是西雅图餐厅,必应返回位于华盛顿西雅图的餐馆。

注意:尽管许多键是可选的,但提供的信息越多,位置结果越精确。

注意:尽管是可选的,但还是建议始终指定用户的地理位置。 如果客户端的 IP 地址未准确反映用户的物理位置(例如,如果客户端使用 VPN),则提供位置尤其重要。 为了获得最佳结果,应包含此标头和 X-Search-ClientIP 标头,但至少应包含此标头。

注意

请记住,使用条款要求遵守所有适用的法律,包含这些标头的用法。 例如,在某些管辖区(如欧洲),在用户设备上放置某些跟踪设备之前,需要获得用户同意。

查询参数

以下是请求可能包含的查询参数。 “必需”列指示是否必须指定参数 。 必须对查询参数值进行 URL 编码。

名称 类型 必需
cc 结果来源的国家/地区的 2 个字符国家/地区代码。 有关可能值的列表,请参阅 市场代码

如果设置此参数,则还必须指定 Accept-language 标头。 必应使用指定语言中查找的第一种受支持语言,并将其与国家/地区代码相结合,以确定市场以返回结果。 如果语言列表不包括支持的语言,必应会查找最接近的语言和支持请求的市场。 或者,必应可能会对结果使用聚合市场或默认市场。

仅当指定多种语言时,才使用此查询参数和 Accept-Language 标头。 否则,应使用 mktsetLang 查询参数。

此参数和 mkt 查询参数相互排斥,不可同时指定两者。
String
mkt 产生结果的市场。 通常, mkt 是用户发出请求的国家/地区。 但是,如果用户不在必应提供结果的国家/地区,则可能是不同的国家/地区。 市场必须采用语言代码国家/地区代码><>的形式。< 例如,en-US。 字符串不区分大小写。 有关可能的市场值的列表,请参阅 市场代码

注意: 如果已知,建议始终指定市场。 指定市场有助于必应路由请求,并返回适当的最佳响应。 如果指定市场代码中未列出的市场,则必应根据要更改的内部映射使用最适合的市场代码。

此参数和 cc 查询参数相互排斥,不可同时指定两者。
String
q 用户的搜索查询字符串。

查询字符串不得为空。 如果为空或未指定,则响应中的建议列表为空。

API 不支持必应高级运算符。 如果查询字符串包含必应运算符,则运算符被视为查询字符串的一部分,而不是运算符。
String
setLang 可用于用户界面字符串的语言。 可以使用 2 个字母或 4 个字母代码指定语言。 首选使用 4 个字母代码。

有关受支持的语言代码列表,请参阅必应支持的语言

如果setlang包含有效的 2 个非特定区域性代码( (fr) )或 (fr-ca) 的有效 4 个字母特定区域性代码,则必应加载本地化字符串。 例如,对于 fr-ca,必应加载 fr 中性区域性代码字符串。

例如,如果setlang无效 (,则 zh) 或 必应 不支持语言 (,例如 af、af-na) ,必应默认为 en (英语) 。

若要指定 2 个字母代码,请将此参数设置为 ISO 639-1 语言代码。

若要指定 4 个字母代码,请使用语言<国家/地区>,其中<语言>><是 ISO 639-1 语言代码 (中性区域性) 和国家</地区是 ISO 3166 国家/>地区 (特定区域性) 代码。 例如,使用 en-US 进行英语美国。

尽管是可选项,但应始终指定语言。 通常情况下,请将 setLang 设置为 mkt 所指定的语言,除非用户希望以另一语言显示用户界面字符串。

此参数和 Accept-Language 标头相互排斥,不可同时指定两者。

用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。 此外,响应对象中 Bing.com 属性的任何链接均会应用指定的语言。
字符串

响应对象

下面是响应可能包含的 JSON 对象。 如果请求成功,响应中的顶级对象是 “建议” 对象。 如果请求失败,则顶级对象为 ErrorResponse

对象 说明
错误 定义已发生的错误。
ErrorResponse 请求失败时响应包含的顶级对象。
QueryContext 定义必应用于请求的查询词。
SearchAction 定义建议的搜索查询。
SuggestionGroup 定义同一类型的一组建议。
建议 响应在请求成功时包括的顶级对象。

错误

定义已发生的错误。

元素 说明 类型
code 用于标识错误类别的错误代码。 如需可能的代码的列表,请参阅错误代码 字符串
message 对错误的说明。 字符串
moreDetails 一个说明,提供关于错误的其他信息。 字符串
parameter 请求中导致错误的查询参数。 字符串
subCode 用于标识错误的错误代码。 例如,如果 code 为 InvalidRequest,则 subCode 可以为 ParameterInvalid 或 ParameterInvalidValue。 字符串
value 查询参数的无效值。 字符串

ErrorResponse

请求失败时响应包含的顶级对象。

名称 类型
_type 类型提示。 字符串
errors 错误的列表,用于说明请求失败原因。 Error[]

QueryContext

定义必应用于请求的查询词。

元素 说明 类型
adultIntent 未使用。 布尔
alterationOverrideQuery 未使用。 字符串
alteredQuery 未使用。 字符串
askUserForLocation 未使用。 字符串
originalQuery 用户的查询词。 字符串

SearchAction

定义查询搜索建议。

名称 类型
displayText 建议的查询词显示在用户界面中。 字符串
query 建议的查询词。

如果用户从建议列表中选择查询词,请使用必应 API 请求中的术语并自行显示搜索结果。 或者,使用字段中的 URL url 将用户发送到建议查询的必应搜索结果页。
String
searchKind 建议的类型。 下面是可能的值。
  • CustomSearch - 建议来自非 Web 搜索建议数据源。
  • WebSearch - 建议来自 Web 搜索建议数据源。
字符串
Url 将用户带到建议查询的必应搜索结果页的 URL。 字符串

SuggestionGroup

定义同一类型的一组建议。

名称 类型
名字 组名称。 该名称标识组包含的建议类型。 例如,Web 搜索建议。 下面是可能的组名称。
  • 自定义 - 组包含来自非 Web 搜索建议数据源的建议。
  • Web - 组包含 Web 搜索建议。
字符串
searchSuggestions 最多 8 条建议的列表。 如果没有建议,则数组为空。

必须按提供的顺序显示所有建议。 该列表按减少相关性的顺序排列。 第一个建议最相关,最后一个建议最不相关。 列表的大小可能会更改。
SearchAction[]

建议

响应在请求成功时包括的顶级对象。

如果服务怀疑拒绝服务攻击,则请求成功 (HTTP 状态代码为 200 OK) 。 但是,响应正文为空。

名称 类型
_type 类型提示,设置为“建议”。 字符串
queryContext 用户的查询字符串。 QueryContext
suggestionGroups 按类型分组的建议查询字符串列表。 例如,Web 搜索建议。 SuggestionGroup[]

错误代码

下面是请求可能返回的 HTTP 状态代码。

状态代码 说明
200 成功。
400 其中一个查询参数丢失或无效。
401 订阅密钥缺失或无效。
403 用户已经过身份验证(例如,用户使用了有效的订阅密钥),但无权访问请求的资源。

如果调用方超出其每月查询配额,必应也可能会返回此状态。
410 请求使用了 HTTP 而非 HTTPS 协议。 HTTPS 是唯一支持的协议。
429 调用方超出其每秒查询配额。
500 意外的服务器错误。

如果请求失败,响应会包含一个 ErrorResponse 对象,该对象包含一系列用于描述错误原因的 Error 对象。 如果错误与参数相关,则 parameter 字段会标识导致问题的参数。 如果错误与参数值相关,则 value 字段会标识无效的参数值。

{
  "_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."
    }
  ]
}

下面是可能的错误代码和子错误代码值。

代码 SubCode 说明
ServerError UnexpectedError
ResourceError
NotImplemented
HTTP 状态代码为 500。
InvalidRequest ParameterMissing
ParameterInvalidValue
HttpNotAllowed
已阻止
只要请求的任何部分无效,必应就会返回 InvalidRequest。 例如,缺少必需参数或参数值无效。

如果错误是 ParameterMissing 或 ParameterInvalidValue,HTTP 状态代码为 400。

如果使用 HTTP 协议而不是 HTTPS 协议,则必应会返回 HttpNotAllowed,且 HTTP 状态代码为 410。
RateLimitExceeded 无子代码 只要超过每秒查询数 (QPS) 或每月查询数 (QPM) 配额,必应就会返回 RateLimitExceeded。

如果超过 QPS,则必应会回 HTTP 状态代码 429;如果超过 QPM,则必应会返回 403。
InvalidAuthorization AuthorizationMissing
AuthorizationRedundancy
当必应无法验证调用方身份时,必应会返回 InvalidAuthorization。 例如,缺少 Ocp-Apim-Subscription-Key 头或订阅密钥无效。

如果指定多个身份验证方法,便会发生冗余。

如果错误是 InvalidAuthorization,HTTP 状态代码为 401。
InsufficientAuthorization AuthorizationDisabled
AuthorizationExpired
当调用方无权访问资源时,必应会返回 InsufficientAuthorization。 如果订阅密钥已遭禁用或到期,就会发生此类错误。

如果错误是 InsufficientAuthorization,HTTP 状态代码为 403。

市场代码

下表列出了可用于指定 mkt 查询参数的市场代码值。 必应仅为这些市场返回内容。 列表可能随时变动。

有关可在查询参数中指定的 cc 国家/地区代码列表,请参阅 国家/地区代码

国家/地区 语言 市场代码
阿根廷 西班牙语 es-AR
澳大利亚 英语 en-AU
奥地利 德语 de-AT
比利时 荷兰语 nl-BE
比利时 法语 fr-BE
巴西 葡萄牙语 pt-BR
加拿大 英语 en-CA
加拿大 法语 fr-CA
智利 西班牙语 es-CL
丹麦 丹麦语 da-DK
芬兰 芬兰语 fi-FI
法国 法语 fr-FR
德国 德语 de-DE
香港特别行政区 繁体中文 zh-HK
印度 英语 en-IN
印度尼西亚 英语 en-ID
意大利 意大利语 it-IT
日本 日语 ja-JP
韩国 韩语 ko-KR
马来西亚 英语 en-MY
墨西哥 西班牙语 es-MX
荷兰 荷兰语 nl-NL
新西兰 英语 en-NZ
挪威 挪威语 no-NO
中华人民共和国 中文 zh-CN
波兰 波兰语 pl-PL
菲律宾共和国 英语 en-PH
俄罗斯 俄语 ru-RU
南非 英语 en-ZA
西班牙 西班牙语 es-ES
瑞典 瑞典语 sv-SE
瑞士 法语 fr-CH
瑞士 德语 de-CH
台湾 繁体中文 zh-TW
土耳其 土耳其语 tr-TR
英国 英语 en-GB
美国 英语 zh-CN
美国 西班牙语 es-US

国家/地区代码

下面是可使用 cc 查询参数指定的国家/地区代码。 列表可能随时变动。

国家/地区 国家/地区代码
阿根廷 AR
澳大利亚 AU
奥地利 AT
比利时 BE
巴西 BR
Canada CA
智利 CL
丹麦 DK
芬兰 FI
法国 FR
德国 DE
香港特别行政区 HK
印度 IN
印度尼西亚 ID
意大利 IT
日本 JP
韩国 KR
马来西亚 MY
墨西哥 MX
荷兰 NL
新西兰 NZ
挪威
中华人民共和国 CN
波兰 PL
葡萄牙 PT
菲律宾共和国 PH
俄罗斯 RU
沙特阿拉伯 SA
南非 ZA
西班牙 ES
瑞典 SE
瑞士 CH
中国台湾 TW
土耳其 TR
United Kingdom GB
United States 美国

必应支持的语言

以下是可在查询参数中指定的setLang必应支持的语言。 列表可能随时变动。

支持的语言 语言代码
阿拉伯语 ar
巴斯克语 eu
孟加拉语 bn
保加利亚语 bg
加泰罗尼亚语 ca
中文(简体) zh-hans
中文(繁体) zh-hant
克罗地亚语 hr
捷克语 cs
丹麦语 da
荷兰语 nl
英语 en
English-United王国 en-gb
爱沙尼亚语 et
芬兰语 fi
法语 fr
加利西亚语 gl
德语 de
古吉拉特语 gu
希伯来语 he
Hindi hi
匈牙利语 hu
冰岛语
意大利语 it
日语 Jp
卡纳达语 kn
韩语 ko
拉脱维亚语 lv
立陶宛语 lt
马来语 ms
马拉雅拉姆语 ml
马拉地语 mr
挪威语(博克马尔语) nb
波兰语 pl
葡萄牙语 (巴西) pt-br
葡萄牙 (葡萄牙) pt-pt
旁遮普语 pa
罗马尼亚语 ro
俄语 ru
塞尔维亚 (西里利奇) sr
斯洛伐克语 sk
斯洛文尼亚语 sl
西班牙语 es
瑞典语 sv
泰米尔语 ta
泰卢固语 te
泰语 th
土耳其语 tr
乌克兰语 uk
越南语 vi