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

Web 搜索 API v7 参考

警告

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

Web 搜索 API 允许向必应发送搜索查询,并返回包含网页、图像等链接的搜索结果。 除了影响搜索结果的查询参数外,本部分还提供有关网页、相关搜索和排名结果的技术详细信息。 有关演示如何发出请求的示例,请参阅 搜索 Web

有关请求应包含的标头的信息,请参阅 请求标头

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

有关响应可能包含的 JSON 对象的信息,请参阅 响应正文。 此参考包含特定于 Web 答案的 JSON 对象。 有关搜索结果可能包含的其他答案类型的 JSON 对象的详细信息,请参阅特定于 API 的参考文档。 例如,如果搜索结果包含图像和新闻答案,请参阅 图像搜索 API新闻搜索 API

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

注意

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

终结点

若要请求 Web 搜索结果,请将 GET 请求发送到:

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

对于多服务订阅,必须在 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 响应标头中将其返回。 仅当用户首次在设备上使用应用时,才不可以在请求中包含此标头。

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

  • 针对应用为设备上的此用户生成的每个必应 API 请求,使用客户端 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 编码。

名称 类型 必需
answerCount 希望响应包含的答案数。 必应返回的答案基于排名。 例如,如果必应返回请求的网页、图像、视频和 relatedSearches,并且将此参数设置为两个 (2) ,则响应包括网页和图像。

如果 responseFilter 在同一请求中包含查询参数并将其设置为网页和新闻,则响应将仅包含网页。

有关将排名答案提升到响应中的信息,请参阅 提升
无符号整数
cc 结果来源的国家/地区的 2 个字符国家/地区代码。 有关可能值的列表,请参阅 市场代码

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

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

此参数和 mkt 查询参数相互排斥,不可同时指定两者。
String
count 要在响应中返回的搜索结果数。 默认值为 10,最大值为 50。 提供的实际结果数可能小于请求获取的结果数。

使用此参数和 offset 参数对结果进行分页。 有关详细信息,请参阅 分页网页

例如,如果用户界面每页显示 10 个搜索结果,则设置为 10,offset将 设置为 count 0 以获取结果的第一页。 对于每个后续页, offset 按 10 (例如,0、10、20) 。 多个页面可能在结果中包含一些重叠。
UnsignedShort
新鲜 按以下不区分大小写的年龄值筛选搜索结果:
  • Day - 返回必应在过去 24 小时内发现的网页

  • 周 - 返回必应在过去 7 天内发现的网页

  • 月份 - 返回过去 30 天内发现的网页

若要获取必应在特定时间范围内发现的文章,请指定格式为 YYYY-MM-DD.的日期范围。YYYY-MM-DD。 例如,&freshness=2019-02-01..2019-05-30。 若要将结果限制为单个日期,请将此参数设置为特定日期。 例如,&freshness=2019-02-04
字符串
mkt 产生结果的市场。 通常, mkt 是用户发出请求的国家/地区。 但是,如果用户不在必应提供结果的国家/地区,则它可能是不同的国家/地区。 市场必须采用语言代码>国家/<地区代码>的形式<。 例如,en-US。 字符串不区分大小写。 有关可能的市场值的列表,请参阅 市场代码

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

此参数和 cc 查询参数相互排斥,不可同时指定两者。
String
offset 从零开始的偏移量,指示返回结果之前要跳过的搜索结果数。 默认值为 0。 偏移量应小于 totalEstimatedMatches - count) (。

使用此参数和 count 参数对结果进行分页。 例如,如果用户界面每页显示 10 个搜索结果,则设置为 10,offset将 设置为 count 0 以获取结果的第一页。 对于每个后续页, offset 按 10 (例如,0、10、20) 。 多个页面可能在结果中包含一些重叠。
无符号短
促进 希望响应包含的以逗号分隔的答案列表,无论其排名如何。 例如,如果将 answerCount) 设置为 2 (2) 以便必应返回排名前两位的答案,但你还希望响应包含新闻,则会将 设置为 promote news。 如果排名靠前的答案是网页、图像、视频和相关搜索,则响应包括网页和图像,因为新闻不是排名答案。 但是,如果设置为 promote “视频”,必应会将视频答案提升到响应中,并返回网页、图像和视频。

要提升的检索结果不计入 answerCount 限制。 例如,如果经过排名的检索结果有新闻、图片和视频,且将 answerCount 设置为 1,将 promote 设置为新闻,则响应会包含新闻和图片。 或者,如果经过排名的检索结果有视频、图像和新闻,则响应会包含视频和新闻。

下面是可能的值。
  • 计算
  • 映像
  • 新闻
  • RelatedSearches
  • SpellSuggestions
  • TimeZone
  • 视频
  • 网页

注意: 仅当指定 answerCount 时,才使用 。
String
q 用户的搜索查询词。 该术语不能为空。

术语可能包含 必应高级运算符。 例如,若要将结果限制为特定域,请使用 site: 运算符。
字符串
responseFilter 要包含在响应中的答案的逗号分隔列表。 如果未指定此参数,响应将包括具有相关数据的所有搜索答案。

下面是可能的筛选器值。
  • 计算
  • 实体
  • 映像
  • 新闻
  • RelatedSearches
  • SpellSuggestions
  • TimeZone
  • 视频
  • 网页

如果想从响应中排除特定类型的内容(例如图像),可以使用 responseFilter 值的连字符(减号)前缀来排除它们。 用逗号分隔排除的类型: &responseFilter=-images,-videos

尽管可以使用此筛选器来获取单个答案,但应改用特定于答案的终结点来获取更丰富的结果。 例如,若要仅接收图像,请将请求发送到 图像搜索 API 终结点之一。

RelatedSearches 和 SpellSuggestions 答案不支持单独的终结点,就像图像搜索 API (只有 Web 搜索 API) 返回它们。

若要包含因排名而排除的答案,请参阅 promote 查询参数。
String
safeSearch 筛选成人内容的网页。 下面是可能的筛选器值。
  • 关闭 - 返回包含成人文本和图像的网页。
  • 中等 - 返回包含成人文本但不包含成人图像或视频的网页。
  • 严格 - 不返回包含成人文本、图像或视频的网页。
默认级别为“中等”。

注意: 对于视频结果,如果 safeSearch 设置为“关”,必应会忽略它并使用“中等”。

注意:如果请求来自必应成人策略要求将 safeSearch 设置为“严格”的某一市场,必应会忽略 safeSearch 值并使用“严格”。

注意:如果使用 site: 查询运算符,则不管 safeSearch 查询参数设置如何,仍有可能出现响应中包含成人内容的情况。 只有在知道网站内容且方案允许使用成人内容的情况下,才应使用 site:
字符串
setLang 可用于用户界面字符串的语言。 可以使用 2 个字母或 4 个字母的代码指定语言。 首选使用 4 个字母的代码。

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

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

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

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

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

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

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

用户界面字符串是用作用户界面中标签的字符串。 JSON 响应对象中有几个用户界面字符串。 此外,响应对象中 Bing.com 属性的任何链接均会应用指定的语言。
字符串
textDecorations 一个布尔值,用于确定显示字符串是否应包含修饰标记,例如命中突出显示字符。 如果 为 true,则字符串可能包含标记。 默认值为 false

若要指定是使用 Unicode 字符还是 HTML 标记作为标记,请参阅 textFormat 查询参数。

有关命中突出显示的信息,请参阅 命中突出显示
布尔
textFormat 用于文本修饰的标记的类型 (请参阅 textDecorations 查询参数) 。

下面是可能的值。
  • 原始 - 使用 Unicode 字符标记需要特殊格式的内容。 Unicode 字符的范围是 E000 到 E019。 例如,必应使用 E000 和 E001 标记查询词的开始和结束,以便突出显示命中。

  • HTML - 使用 HTML 标记标记需要特殊格式的内容。 例如,使用 <b> 标记突出显示显示字符串中的查询词。

默认值为 Raw。

有关标记的列表,请参阅 命中突出显示

对于包含可转义 HTML 字符(如 、 和 )<的显示字符串,如果 textFormat 设置为 HTML,则必应根据需要转义字符 (,例如,<转义为 &lt;&) 。 >

有关使用嵌入 Unicode 字符处理字符串的信息,请参阅 命中突出显示
字符串

响应对象

注意

为了遵守法国新的欧盟版权指令,必应 Web、新闻、视频、图像和所有自定义搜索 API 必须省略法国用户某些欧盟新闻来源的某些内容。 删除的内容可能包括缩略图和视频、视频预览以及这些来源的搜索结果附带的代码片段。 因此,必应 API 可能会向法国用户提供更少的结果,包括缩略图和视频、视频预览和代码片段。

以下是响应中可以包含的 JSON 响应对象。 如果请求成功,则响应中的顶级对象是 SearchResponse 对象。 如果请求失败,则顶级对象为 ErrorResponse 对象。

此列表包含特定于 Web 答案的 JSON 对象。 有关搜索结果可能包含的其他答案类型的 JSON 对象的详细信息,请参阅特定于 API 的参考文档。 例如,如果搜索结果包含图像和新闻答案,请参阅 图像 API新闻 API

Object 说明
计算 定义表达式及其答案。
实体 定义实体,例如人员、地点或事物。
错误 定义发生的错误。
ErrorResponse 请求失败时响应包含的顶级对象。
Identifiable 定义资源 ID。
LicenseAttribution 定义许可证属性的协定规则。
LinkAttribution 定义链接属性的协定规则。
MediaAttribution 定义媒体属性的协定规则。
查询 定义查询字符串。
QueryContext 如果指定的查询字符串包含拼写错误,则定义必应用于请求的查询上下文。
RankingGroup 定义搜索结果组,例如 mainline。
RankingItem 定义要显示的排名组项。
RankingResponse 定义应将内容置于搜索结果页的何处以及应采用什么顺序。
RelatedSearchAnswer 定义其他人进行的相关查询的列表。
SearchResponse 请求成功时响应包含的顶级对象。
SpellSuggestions 定义可能表示用户意向的建议查询字符串。
TextAttribution 定义纯文本属性的协定规则。
TimeZone 定义一个或多个地理位置的日期和时间。
TimeZoneInformation 定义有关地理位置的时区信息。
WebAnswer 定义相关网页链接的列表。
网页 定义与查询相关的网页。

实体

定义实体,例如人员、地点或事物。

名称 类型
bingId 唯一标识此实体的 ID。 String
合同Rules 显示实体时必须遵守的规则列表。 例如,规则可以控制实体描述的归属。

以下合同规则可能适用。


并非所有实体都包含规则。 如果实体提供合同规则,则必须遵守这些规则。 有关使用合同规则的详细信息,请参阅 归属数据
Object[]
description 实体的简短说明。 String
entityPresentationInfo 有关实体的其他信息,例如,可用于确定实体类型的提示。 若要确定实体的类型,请使用 entityScenarioentityTypeHint 字段。 例如,字段可帮助你确定实体是主导实体还是消除歧义实体,以及它是人还是电影。 如果必应认为只有一个实体满足请求,则实体是主导实体。 如果多个实体可以满足请求,则实体是消除歧义实体,用户需要选择他们感兴趣的实体。 EntityPresentationInfo
image 实体的图像。 图像
name 实体的名称。 字符串
webSearchUrl 将用户带到此实体的必应搜索结果页的 URL。 字符串

EntityAnswer

定义实体答案。

名称 类型
queryScenario 支持的查询方案。 此字段设置为 DominantEntity 或 DisambiguationItem。 如果必应确定只有一个实体满足请求,则 字段设置为 DominantEntity。 例如,书籍、电影、人物或景点。 如果多个实体可以满足请求,则 字段设置为 DisambiguationItem。 例如,如果请求使用电影专营权的通用标题,则实体的类型可能是 DisambiguationItem。 但是,如果请求指定了特许经营权中的特定标题,则实体的类型可能是 DominantEntity。 字符串
value 实体列表。 Entity[]

EntityPresentationInfo

定义有关实体的其他信息,例如类型提示。

名称 类型
entityScenario 支持的方案。 字符串
entityTypeDisplayHint 实体提示的显示版本。 例如,如果 entityTypeHints 是 艺术家,则此字段可能设置为 American Singer 字符串
entityTypeHint 指示实体类型的提示列表。 该列表可以包含单个提示(如 Movie)或一系列提示(如 Place、LocalBusiness、Restaurant)。 数组中的每个后续提示都会缩窄实体的类型范围。

有关可能类型的列表,请参阅 实体类型。 如果对象不包含此字段,则假定为 Generic。
String[]

计算

定义表达式及其答案。

元素 说明 类型
表达 数学或转换表达式。

如果查询包含将度量单位转换为 (例如,米到英尺) 的请求,则此字段包含 from 单位,并 value 包含 单位。

如果查询包含数学表达式(如 2+2),则此字段包含表达式并 value 包含答案。

请注意,数学表达式可以规范化。 例如,如果查询是 sqrt (4^2+8^2) ,则规范化表达式可能是 sqrt ( (4^2) + (8^2) ) 。

如果用户的查询是数学问题,并且 textDecorations 查询参数设置为 true,则表达式字符串可能包含格式标记。 例如,如果用户的查询是 log (2) ,则规范化表达式将包含下标标记。 有关详细信息,请参阅 命中突出显示
字符串
value 表达式的答案。 字符串

错误

定义已发生的错误。

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

ErrorResponse

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

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

Identifiable

定义资源的标识。

名称 类型
id 标识符。 String

映像

定义图像。

注意

由于 URL 格式和参数可能会更改,因此应按原样使用所有图像 URL;不应依赖 URL 格式或参数。 例外是 调整大小和裁剪缩略图图像所讨论的参数和值。

名称 类型
高度 源图像的高度(以像素为单位)。 无符号短
hostPageUrl 包含图像的网页的 URL。

此 URL 和 contentUrl 可能是相同的 URL。
String
name 包含有关图像的随机信息的可选文本字符串。 字符串
provider 映像的源。 数组将包含单个项。

必须将映像归因于提供程序。 例如,当光标悬停在图像上时,可以显示提供程序的名称,或者使图像成为指向找到图像的提供商网站的点击链接。
组织[]
thumbnailUrl 图像缩略图的 URL。 有关调整图像大小的信息,请参阅 调整缩略图大小和裁剪缩略图 String
width 源图像的宽度(以像素为单位)。 无符号短

LicenseAttribution

定义许可证属性的协定规则。

名称 类型
_type 一种类型提示,设置为 LicenseAttribution。 字符串
license 内容使用许可证。 许可证
licenseNotice 将显示在目标字段旁边的许可证。 例如,“文本需 CC-BY-SA 许可证”。

license 字段中使用许可证的名称和 URL,以便创建介绍许可证详细信息的网站的超链接。 然后,将 licenseNotice 字符串中的许可证名称(例如 CC-BY-SA)替换为刚创建的超链接。
字符串
mustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。 如果为 true,则必须将内容置于附近。 如果为 false,或者此字段不存在,则内容可由调用方随意放置。 Boolean
targetPropertyName 规则应用到的字段的名称。 字符串

LinkAttribution

定义链接属性的协定规则。

名称 类型
_type 一种类型提示,设置为 LinkAttribution。 字符串
mustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。 如果为 true,则必须将内容置于附近。 如果为 false,或者此字段不存在,则内容可由调用方随意放置。 Boolean
targetPropertyName 规则应用到的字段的名称。

如果目标未指定,则此属性适用于整个实体,会在实体呈现后立即显示。 如果有多个文本和链接属性规则未指定目标,则应将它们连接起来,并使用“数据来自: ”标签来显示它们。 例如,“来自 <提供程序名称1> 的数据| <provider name2>”。
字符串
text 属性文本。 字符串
url 提供者网站的 URL。 使用 text 和 URL 创建超链接。 字符串

MediaAttribution

定义媒体属性的协定规则。

名称 类型
_type 一种类型提示,设置为 MediaAttribution。 字符串
mustBeCloseToContent 一个布尔值,确定是否必须将规则的内容置于规则所应用到的字段的附近。 如果为 true,则必须将内容置于附近。 如果为 false,或者此字段不存在,则内容可由调用方随意放置。 Boolean
targetPropertyName 规则应用到的字段的名称。 字符串
url 一种 URL,用于创建媒体内容的超链接。 例如,如果目标为图像,则可使用此 URL 使图像变得可以单击。 String

MetaTag

定义网页的元数据。

名称 类型
内容 元数据。 字符串
name 元数据的名称。 字符串

组织

定义发布者。

注意,发布者可能提供其名称和/或网站。

名称 类型
name 发布者名称。 字符串
url 发布者网站的 URL。

请注意,发布者可能未提供网站。
字符串

查询

定义搜索查询。

SpellSuggestions 对象使用此对象来建议可能表示用户意图的查询字符串。 RelatedSearchAnswer 还使用它返回其他用户所做的相关查询。

名称 类型
displayText 查询术语的显示版本。 此版本的查询词可能包含突出显示在查询字符串中找到的搜索词的特殊字符。 仅当查询启用命中突出显示 (看到 textDecorations 查询参数) 时,字符串才包含突出显示字符。 有关命中突出显示的详细信息,请参阅 命中突出显示 String
text 查询字符串。 将此字符串用作新搜索请求中的查询词。 String
webSearchUrl 将用户带到必应搜索结果页进行查询的 URL。

只有相关的搜索结果包括此字段。
字符串

QueryContext

定义必应用于请求的查询字符串。

元素 说明 类型
adultIntent 一个布尔值,表示指定的查询是否有成人意向。 如果查询具有成人意向,则值为 true

如果 为 true,并且请求的 safeSearch 查询参数设置为 Strict,则响应仅包含新闻结果(如果适用)。
Boolean
alterationOverrideQuery 一个查询字符串,用于强制必应使用原始字符串。 例如,如果查询字符串正在 顺风中搜索,则替代查询字符串为 +saling downwind。 请记住对查询字符串进行编码,这会导致 %2Baling+downwind

仅当原始查询字符串包含拼写错误时, 对象才包含此字段。
字符串
alteredQuery 必应用于执行查询的查询字符串。 如果原始查询字符串包含拼写错误,必应会使用更改的查询字符串。 例如,如果查询字符串为 saling downwind,则更改的查询字符串为 sailing downwind

仅当原始查询字符串包含拼写错误时, 对象才包含此字段。
字符串
askUserForLocation 一个布尔值,指示必应是否需要用户的位置才能提供准确结果。 如果已使用 X-MSEdge-ClientIPX-Search-Location 标头指定用户的位置,则可忽略此字段。

对于需要用户的位置才能提供准确结果的位置感知型查询,例如“今天的天气”或“我附近的餐馆”,此字段设置为 true

对于包含位置的位置感知型查询(例如“西雅图的天气”),此字段设置为 false。 对于不识别位置的查询(例如“畅销书”),此字段也设置为 false
Boolean
originalQuery 请求中指定的查询字符串。 字符串

RankingGroup

定义搜索结果组,例如 mainline。

名称 类型
items 要显示在组中的搜索结果项的列表。 RankingItem[]

RankingItem

定义要显示的搜索结果项。 有关如何使用 ID 的详细信息,请参阅 使用排名显示结果

名称 类型
answerType 一个答案,包含要显示的项。 例如,新闻。

使用 类型在 SearchResponse 对象中查找答案。 类型是字段的名称 SearchResponse
字符串
resultIndex 答案中项的从零开始的索引。

如果项不包含此字段,则显示答案中的所有项。 例如,显示“新闻”答案中的所有新闻文章。
Integer
value 一个 ID,用于标识要显示的答案或要显示的答案的项。 如果此 ID 标识某个答案,则显示该答案的所有项。 Identifiable

RankingResponse

定义应将内容置于搜索结果页的何处以及应采用什么顺序。

名称 类型
mainline 要显示在主线中的搜索结果。 RankingGroup
pole 要获得最明显的处理(例如,显示在主线和边栏上方)的搜索结果。 RankingGroup
sidebar 要显示在边栏中的搜索结果。 RankingGroup

RelatedSearchAnswer

定义其他人进行的相关查询的列表。

名称 类型
id 唯一标识相关搜索答案的 ID。

仅当排名答案指定在组中显示所有相关搜索时, 对象才包括此字段。 有关如何使用该 ID 的详细信息,请参阅 使用排名显示结果
字符串
value 由其他人进行的相关查询的列表。 Query[]

SearchResponse

用于搜索请求的响应的顶级对象。

默认情况下,搜索 API 包括所有答案,除非:

  • 查询指定 responseFilter 查询参数以限制答案

  • 一个或多个搜索组件不返回结果 (例如,没有新闻结果与查询)

  • 订阅密钥无权访问搜索组件。

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

名称 类型
_type 类型提示。 字符串
计算 数学表达式或单位转换表达式的答案。 计算
实体 与搜索查询相关的实体列表。 EntityAnswer
图像 与搜索查询相关的图像列表。 映像
news 与搜索查询相关的新闻文章列表。 资讯
queryContext 必应用于请求的查询字符串。

仅当查询字符串包含拼写错误或具有成人意向时,响应才包含上下文。
QueryContext
rankingResponse 必应建议你显示搜索结果的顺序。 RankingResponse
relatedSearches 其他人进行的相关查询的列表。 RelatedSearchAnswer
spellSuggestions 可能表示用户意向的查询字符串。 SpellSuggestions
时区 一个或多个地理位置的日期和时间。 TimeZone
视频 与搜索查询相关的视频列表。 视频
网页 与搜索查询相关的网页列表。 WebAnswer

SpellSuggestions

定义可能表示用户意向的建议查询字符串。

如果必应确定用户可能打算搜索其他内容,则搜索结果将包含此响应。 例如,如果用户搜索 alon brown,必应可能会根据 Alon Brown) 的其他人过去的搜索来确定用户可能打算搜索 Alton Brown,而不是 (。

名称 类型
id 唯一标识拼写建议答案的 ID。

使用 排名响应 显示拼写建议时,将使用此字段。 有关如何使用该 ID 的详细信息,请参阅 使用排名显示结果
字符串
value 可能表示用户意图的建议查询字符串的列表。

该列表仅包含一个 Query 对象。
Query[]

TextAttribution

定义纯文本属性的协定规则。

名称 类型
_type 一种类型提示,设置为 TextAttribution。 字符串
text 属性文本。

文本属性适用于整个实体,会在实体呈现后立即显示。 如果有多个文本或链接属性规则未指定目标,则应将它们连接起来,并使用“数据来自: ”标签来显示它们。
String

TimeZone

定义一个或多个地理位置的数据和时间。

名称 类型
otherCityTimes 附近时区的日期和时间的列表。 TimeZoneInformation[]
primaryCityTime 查询中指定的地理位置的数据和时间(以 UTC 为单位)。

如果查询指定了特定地理位置 (例如城市) ,则此对象包含该地理位置的名称以及该位置的当前日期和时间(以 UTC 为单位)。

如果查询指定了常规地理位置(如州或国家/地区),则此对象包含指定州或国家/地区中找到的主要城市或州/地区的日期和时间。 如果位置包含其他时区,则 otherCityTimes 字段包含位于其他时区的城市或州的数据和时间。
TimeZoneInformation

TimeZoneInformation

定义地理位置的日期和时间。

名称 类型
位置 地理位置的名称。

例如,县;城市;城市、州;城市、州、国家/地区;或时区。
String
time 以形式 YYYY-MM-DDThh;mm:ss.sssssZ 指定的数据和时间。 字符串
utcOffset 与 UTC 的偏移量。 例如 UTC-7。 字符串

WebAnswer

定义相关网页链接的列表。

名称 类型
id 唯一标识 Web 答案的 ID。

仅当排名答案建议在一个组中显示所有 Web 结果时, 对象才包括此字段。 有关如何使用该 ID 的详细信息,请参阅 使用排名显示结果
字符串
someResultsRemoved 一个布尔值,指示响应是否从答案中排除了某些结果。 如果必应排除了某些结果,则值为 true Boolean
totalEstimatedMatches 与查询相关的估计网页数。 将此数字与 countoffset 查询参数一起用于对结果进行分页。 Long
value 与查询相关的网页列表。 WebPage[]
webSearchUrl 请求网页的必应搜索结果的 URL。 字符串

网页

定义与查询相关的网页。

名称 类型
about 仅限内部使用。 Object
dateLastCrawled 必应上次爬网网页的时间。 日期的格式为 YYYY-MM-DDTHH:MM:SS。 例如,2015-04-13T05:23:39。 字符串
deepLinks 必应在包含此网页的网站中找到的相关内容的链接列表。

Webpage此上下文中的 对象仅name包括 、urlurlPingSuffixsnippet 字段。
网页[]
displayUrl 网页的显示 URL。 URL 仅用于显示目的,格式不正确。 字符串
id 在 Web 结果列表中唯一标识此网页的 ID。

仅当排名答案指定将网页与其他搜索结果混合时,对象才包含此字段。 每个网页都包含一个 ID,该 ID 与排名答案中的 ID 相匹配。 有关详细信息,请参阅 使用排名显示结果
String
名字 网页的名称。

使用此名称以及 url 创建超链接,单击该超链接时会将用户带到网页。
字符串
提到 仅限内部使用。 Object
searchTags 网页所有者在网页上指定的搜索标记列表。 API 仅返回索引搜索标记。

对象的 name 字段 MetaTag 包含索引搜索标记。 搜索标记以 search.* 开头, (例如 search.assetId) 。 字段 content 包含标记的值。
MetaTag[]
片段 网页中描述其内容的一段文本。 String
Url 网页的 URL。

将此 URL 与 一起使用 name ,创建一个超链接,单击该超链接时会将用户带到网页。
String

实体类型

本部分包含可能的实体提示。 提示按实体类别分组。

下面是基本实体类型。

  • 泛型
  • 人员
  • 位置
  • 媒体
  • 组织

下面是属于 Place 基类型的实体提示。

  • 景点
  • 城市
  • Continent
  • 国家/地区
  • Hotel
  • House
  • LocalBusiness
  • 本地性
  • MinorRegion
  • 邻近区域
  • 其他
  • PointOfInterest
  • PostalCode
  • RadioStation
  • 区域
  • 餐厅
  • 状态
  • StreetAddress
  • SubRegion
  • TouristAttraction
  • 旅行

下面是属于 Media 基类型的实体提示。

  • 书籍
  • 电影
  • TvSeason
  • TvShow
  • 游戏

下面是与事件相关的实体提示。

  • 事件

下面是与专业相关的实体提示。

  • Actor
  • 艺术家
  • 律师

下面是与教育相关的实体提示。

  • CollegeOrUniversity
  • School
  • 专业

下面是不相关的实体提示。

  • 动物
  • 汽车
  • 药物
  • 食物
  • 产品
  • SportsTeam

错误代码

下面是请求可能返回的 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