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

新闻搜索 API v5 参考

  • 项目

警告

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

注意

此 API 的新版本可用。 请参阅 必应新闻搜索 API v7。 有关升级的信息，请参阅 升级指南。

新闻搜索 API 允许你向必应发送搜索查询并取回相关新闻文章的列表。 本部分提供有关用于请求新闻文章的查询参数和标头以及包含它们的 JSON 响应对象的技术详细信息。 有关演示如何发出请求的示例，请参阅 在 Web 上搜索新闻。

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

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

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

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

终结点

若要请求新闻文章，请将 GET 请求发送到以下 URL 之一：

URL 说明
https://api.cognitive.microsoft.com/bing/v5.0/news 按类别返回热门新闻文章。 例如，可以请求热门体育或娱乐文章。 有关指定类别的信息，请参阅 类别 查询参数。
https://api.cognitive.microsoft.com/bing/v5.0/news/search 根据用户的搜索查询返回新闻文章。 如果搜索查询为空，则该调用将返回热门新闻文章。
https://api.cognitive.microsoft.com/bing/v5.0/news/trendingtopics 返回当前在社交网络上的热门新闻主题。

注意： 仅适用于 en-US 和 zh-CN 市场。

请求必须使用 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 查询参数。 否则，请使用 mkt 和 setLang 查询参数。

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

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

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

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

在认知服务中注册此服务时收到的订阅密钥。
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-Search-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 键的情况下才指定此键。

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

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

注意

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

查询参数

以下是请求可能包含的查询参数。 请查看所需参数的“必需”列。 查询参数值必须经过 URL 编码。

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

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

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

此参数和 mkt 查询参数相互排斥，不可同时指定两者。		 String 否
类别 要返回的文章的类别。 例如，体育文章或娱乐文章。 有关可能类别的列表，请参阅 按市场分类的新闻类别。

注意： 此参数仅适用于新闻类别请求。

如果未指定此参数，响应将同时包括：
  • 标题文章通常从任何类别在过去 24 小时内发布;但是，某些文章可能较旧。

    如果文章是标题，则文章的 标题 字段设置为 true。 默认情况下，响应最多包含 12 篇标题文章和群集。 若要指定要返回的标题文章数，请 headlineCount 设置查询参数。

  • 每个父类别的文章最多 (四篇文章，每个类别) 群集。

如果未指定 headlineCount，并且市场支持 8 个类别，则响应最多包括 44 篇文章和群集 (12 篇标题文章和群集，以及 32 篇特定于类别的文章和群集) 。 由于群集包含多个项目，因此此示例中的文章数（44）可能更多。 例如，响应可能包含 11 篇标题文章和 1 个分类，其中包含 4 篇相关标题文章，共 15 篇标题文章。		 String 否
count 响应中要返回的新闻文章数。 提供的实际结果数可能小于请求获取的结果数。 默认值为 10，可以指定的最大值为 100。

对于热门主题，默认值是所有热门新闻主题 (大约 55 篇文章) 。

可以将此参数与 参数一起使用 offset 来对结果进行分页。 例如，如果用户界面每页显示 20 篇文章，则设置为 count 20， offset 设置为 0 以获取结果的第一页。 对于每个后续页面，将递增 offset 20 (例如 0、20、40) 。 多个页面可能在结果中包含一些重叠。

注意： 群集计为单个项。 例如，如果将计数设置为 10，则响应可能包含 9 篇文章和 1 个群集，但群集可能包含 5 篇文章。

注意： 如果请求新闻类别，则仅在指定类别参数时才指定此参数。 如果未指定类别参数，则忽略此参数。		 UnsignedShort 否
新鲜 按年龄筛选新闻文章。 年龄是指必应发现文章的日期和时间。 下面是可能的筛选器值。
  • Day - 返回过去 24 小时内发现的新闻文章

  • 周 - 返回过去 7 天内发现的新闻文章

  • 月份 - 返回过去 30 天内发现的新闻文章
  • 年份 - 返回去年发现的图像

注意： 热门新闻忽略此参数。		 字符串 否
headlineCount 要返回的标题文章和群集数。 默认值为 12。

仅当未指定类别参数时，才指定此参数。 如果指定类别参数，则忽略此参数。

注意： 此参数仅适用于新闻类别请求。		 UnsignedShort 否
mkt 产生结果的市场。 通常， mkt 是用户发出请求的国家/地区。 但是，如果用户不位于必应提供结果的国家/地区，则可能是不同的国家/地区。 市场必须采用语言代码>-国家/<地区代码>的形式<。 例如，en-US。 字符串不区分大小写。 有关可能的市场值的列表，请参阅 市场代码。

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

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

将此参数与 参数一起使用 count ，对结果进行分页。 例如，如果用户界面每页显示 20 篇文章，则设置为 count 20， offset 设置为 0 以获取结果的第一页。 对于每个后续页面，将递增 offset 20 (例如 0、20、40) 。 多个页面可能在结果中包含一些重叠。

注意： 群集计为单个项。 例如，如果将计数设置为 10，则响应可能包含 9 篇文章和 1 个群集，但群集可能包含 5 篇文章。

注意： 如果请求新闻类别，则仅在指定类别参数时才指定此参数。 如果未指定类别参数，则忽略此参数。		 无符号短 否
originalImg 一个布尔值，用于确定图像的 contentUrl 是包含指向原始文章图像的缩略图的 URL 还是图像本身。

如果文章包含图像，并且此参数设置为 true，请使用图像字段中的 contentUrl URL 从发布者的网站下载原始图像。 否则，如果此参数为 false，则图像的 contentUrl 和 thumbnailUrl URL 都指向同一缩略图。

默认值为 false。

只有新闻搜索 API 支持此参数。 调用 Web 搜索 API 时，请勿指定此参数。

注意： 热门新闻忽略此参数。		 布尔 否
q 用户的搜索查询字符串。 如果查询字符串为空 (例如 q=) ，则响应包括热门新闻报道。

查询字符串可能包含 必应高级运算符。 例如，若要将新闻限制为特定域，请使用 site： 运算符。

如果按类别获取新闻文章，请不要包含此参数。

注意： 热门新闻忽略此参数。		 String 是
safeSearch 用于筛选成人内容的新闻文章的筛选器。 下面是可能的筛选器值。
  • 关闭 - 返回包含成人文本、图像或视频的新闻文章。

  • 中等 - 返回包含成人文本的新闻文章;但是，这些文章不包括成人图像或视频。

  • 严格 - 请勿返回包含成人文本、图像或视频的新闻文章。

如果未指定，则默认值为“中等”。

注意：如果请求来自必应成人策略要求将 safeSearch 设置为“严格”的某一市场，必应会忽略 safeSearch 值并使用“严格”。		 字符串 否
setLang 可用于用户界面字符串的语言。 使用 ISO 639-1 2 字母语言代码指定语言。 例如，英语的语言代码是 EN。 默认为 EN（英语）。

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

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

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

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

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

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

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

默认值为 Raw。

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

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

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

响应对象

注意

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

下面是响应可能包含的 JSON 对象。 如果请求成功，如果终结点为 /news/search 或 /news，则响应中的顶级对象为 News 对象;如果终结点为 /news/trendingtopicAnswer，则为 TrendingTopicAnswer 。 如果请求失败，则顶级对象为 ErrorResponse 对象。

对象 说明
错误 定义发生的错误。
ErrorResponse 定义请求失败时响应包含的顶级对象。
图像 定义新闻相关图像的缩略图。
资讯 定义响应在新闻请求成功时包括的顶级对象。
NewsArticle 定义新闻文章。
组织 定义运行文章的提供程序。
查询 定义搜索查询字符串。
RelatedTopic 定义与搜索查询相关的新闻文章列表。
缩略图 定义指向相关图像的链接。
主题 定义热门新闻主题。
TrendingTopics 定义趋势主题请求成功时响应包括的顶级对象。

错误

定义发生的错误。

元素 说明 类型
code 用于标识错误的错误代码。 如需可能的代码的列表，请参阅错误代码。 字符串
message 对错误的说明。 字符串
parameter 请求中导致错误的查询参数。 字符串
value 查询参数的无效值。 字符串

ErrorResponse

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

名称 值 类型
_type 类型提示。 字符串
errors 描述请求失败原因的 Error 对象的数组。 Error[]

Image

定义新闻相关图像的缩略图。

名称 值 类型
provider 标识映像所有者的 Organization 对象的数组。 组织
thumbnail 指向新闻相关图像的缩略图的链接。 缩略图
url 图像的 URL。 字符串

新闻

定义当新闻请求成功时响应包含的顶级对象。

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

名称 值 类型
_type 类型提示。 字符串
id 唯一标识新闻答案的 ID。

有关如何使用此字段的信息，请参阅 使用排名在 Web 搜索 API 中显示结果。		 String
readLink 返回此答案的 URL。 若要使用 URL，必须根据需要追加查询参数，并包含 Ocp-Apim-Subscription-Key 标头。

新闻搜索 API 和 Web 搜索 API 都包含此字段。 通常，当 URL 包含在搜索响应中并且想要直接查询新闻搜索 API 时，会使用该 URL。		 字符串
relatedTopics 与搜索查询相关的新闻文章列表。 RelatedTopic[]
totalEstimatedMatches 与查询相关的新闻文章的估计数量。 将此数字与 count 和 offset 查询参数一起用于对结果进行分页。

仅当调用新闻搜索 API 时，响应才包括此字段。 Web 搜索 API 在响应中不包括此字段。		 Long
value NewsArticle 对象的数组，其中包含与查询相关的新闻文章的相关信息。

如果没有要为请求返回的结果，则数组为空。		 NewsArticle[]

NewsArticle

定义新闻文章。

名称 值 类型
类别 文章所属的新闻类别。 例如，“体育”。 如果无法确定新闻类别，则文章不包含此字段。

有关可能类别的列表，请参阅 按市场分类的新闻类别。

如果请求指定Sports-Tennis类别，则 category 属性可能包含 Sports-Tennis 或 Sports。		 String
clusteredArticles 相关新闻文章的列表。 NewsArticle[]
datePublished 必应发现文章的日期和时间。 日期的格式为 YYYY-MM-DDTHH：MM：SS。 字符串
描述 新闻文章的简短说明。 String
标题 一个布尔值，指示新闻文章是否为标题。 如果 为 true，则文章为标题;否则， false (或不存在) 。

注意： 本文仅针对未指定类别查询参数的新闻类别请求包含此字段。		 布尔
id 在文章列表中唯一标识此文章的 ID。

有关如何使用此字段的信息，请参阅 使用排名在 Web 搜索 API 中显示结果。		 String
图像 与新文章相关的图像。

Image此上下文中的 对象仅thumbnail包含 字段。		 图像
名字 项目的名称。

将此名称与 URL 一起使用，以创建一个超链接，单击该超链接时会将用户转到新闻文章。		 String
供应商 运行本文的提供程序的列表。 组织[]
Url 新闻文章的 URL。

将此 URL 与 一起使用 name 可创建超链接，单击该超链接时，用户可转到新闻文章。		 字符串

组织

定义运行文章的提供程序。

名称 值 类型
_type 类型提示。 字符串
name 运行文章的提供程序的名称。 String

查询

定义搜索查询字符串。

名称 值 类型
text 返回热门主题的查询字符串。 String

RelatedTopic

定义与搜索查询相关的新闻文章列表。

名称 值 类型
relatedNews 相关新闻文章的列表。 NewsArticle
名字 返回相关新闻文章的相关查询字符串。 字符串
webSearchUrl 将用户带到相关查询的必应搜索结果的 URL。 字符串

缩略图

定义指向相关映像的链接。

名称 值 类型
contentUrl 图像的 URL。 字符串
高度 图像的高度（以像素为单位）。 无符号短
宽度 图像的宽度（以像素为单位）。 无符号短

主题

定义热门新闻主题。

名称 值 类型
图像 指向相关图像的链接。

Image此上下文中的 对象仅url包含 和 provider 字段。 字段 provider 是标识图像提供程序的 Organization 对象的数组。		 Image
isBreakingNews 一个布尔值，指示主题是否被视为突发新闻。 如果主题被视为突发新闻，则值为 true ;否则为 false。 布尔
名字 热门主题的标题。 String
query 返回此热门主题的搜索查询字符串。 查询
webSearchUrl 热门新闻主题的必应搜索结果的 URL。 字符串


TrendingTopics

定义当热门主题请求成功时响应包含的顶级对象。

名称 值 类型
value 必应热门新闻主题列表。

如果没有要为请求返回的结果，则数组为空。		 Topic[]

按市场划分的新闻类别

下面是可以将 类别 查询参数设置为的可能新闻类别的列表。 可以将 设置为 category 父类别（如娱乐）或其子类别之一（如Entertainment_MovieAndTV）。 如果设置为 category 父类别，则它将包括其一个或多个子类别中的文章。 如果设置为 category 子类别，则它仅包含子类别中的文章。

市场 支持的类别
英国 (en-GB)
  • Microsoft Store
  • 娱乐
  • 健康产业
  • 政治
  • ScienceAndTechnology
  • 体育游戏
  • 英国
  • World
美国 (en-US)
  • Microsoft Store
  • 娱乐

    • Entertainment_MovieAndTV
    • Entertainment_Music
  • 健康产业
  • 政治
  • ScienceAndTechnology

    • 技术
    • 科学
  • 体育游戏

    • Sports_Golf
    • Sports_MLB
    • Sports_NBA
    • Sports_NFL
    • Sports_NHL
    • Sports_Soccer
    • Sports_Tennis
    • Sports_CFB
    • Sports_CBB
  • 美国

    • US_Northeast
    • US_South
    • US_Midwest
    • US_West
  • World

    • World_Africa
    • World_Americas
    • World_Asia
    • World_Europe
    • World_MiddleEast

错误代码

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

状态代码 说明
200 调用成功。
400 其中一个查询参数丢失或无效。
401 订阅密钥缺失或无效。
403 例如，用户 (使用有效的订阅密钥) 但对请求的资源没有权限。

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

如果请求失败，响应的正文将包含 一个 ErrorResponse 对象。 响应对象将包含错误代码和错误说明。 如果错误与参数相关，则 parameter 字段将标识问题参数。 如果错误与参数值相关，则 value 字段将标识无效的值。

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


{
  "_type": "ErrorResponse", 
  "errors": [
    {
      "code": "AuthorizationMissing", 
      "message": "Authorization is required.", 
    }
  ]
}

下面是可能的错误代码。

错误代码 说明
RequestParameterMissing 请求缺少必需的参数。 字段 parameter 标识缺少的参数。
RequestParameterInvalidValue 参数值无效。 字段 parameter 标识包含无效值的参数， value 字段包含无效的值。
ResourceAccessDenied 调用方没有访问资源的权限。 如果订阅密钥已禁用或过期，则会发生此错误。
ExceededVolume 调用方超出其每月查询数 (QPM) 配额。
ExceededQpsLimit 调用方在 QPS) (每秒超过其查询数。
已禁用 调用方没有访问资源的权限。
UnexpectedError 服务器上发生意外错误。 请稍后再试。
DataSourceErrors 访问资源时出错。
AuthorizationMissing 必应无法对调用方进行身份验证。 如果缺少标头， Ocp-Apim-Subscription-Key 则可能发生此错误。
HttpNotAllowed 请求使用 HTTP 协议而不是 HTTPS 协议;必应仅支持 HTTPS。
InvalidAuthorization 必应无法对调用方进行身份验证。 如果订阅密钥无效，则可能会发生这种情况。
InsufficientScope 调用方没有访问资源的权限。 如果订阅密钥已过期，则可能发生此错误。

市场代码

下表列出了可用于指定 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 美国