您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

新闻搜索 API 升级指南News Search API upgrade guide

警告

必应搜索 API 将从认知服务迁移到必应搜索服务。Bing Search APIs are moving from Cognitive Services to Bing Search Services. 从 2020 年 10 月 30 日开始,必应搜索的任何新实例都需按照此处所述的过程进行预配。Starting October 30, 2020, any new instances of Bing Search need to be provisioned following the process documented here. 使用认知服务进行预配的必应搜索 API 将在未来三年或在企业协议结束前(以先发生者为准)得到支持。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. 有关迁移说明,请参阅必应搜索服务For migration instructions, see Bing Search Services.

本升级指南确定了必应新闻搜索 API 版本 5 与版本 7 的不同之处。This upgrade guide identifies the changes between version 5 and version 7 of the Bing News Search API. 本指南有助于发现需要更新为使用版本 7 的应用部分。Use this guide to help you identify the parts of your application that you need to update to use version 7.

中断性变更Breaking changes

终结点Endpoints

  • 终结点的版本号已从 v5 更改为 v7。The endpoint's version number changed from v5 to v7. 例如,https://api.cognitive.microsoft.com/bing/v7.0/news/searchFor example, https://api.cognitive.microsoft.com/bing/v7.0/news/search.

错误响应对象和错误代码Error response objects and error codes

  • 现在,所有失败请求的响应正文都应包含 ErrorResponse 对象。All failed requests should now include an ErrorResponse object in the response body.

  • 已将以下字段添加到 Error 对象。Added the following fields to the Error object.

    • subCode—如果可能,将错误代码分入各个独立桶中subCode—Partitions the error code into discrete buckets, if possible
    • moreDetails—有关 message 字段中错误的更多信息moreDetails—Additional information about the error described in the message field
  • 已将 v5 错误代码替换为以下可取的 codesubCode 值。Replaced the v5 error codes with the following possible code and subCode values.

代码Code SubCodeSubCode 说明Description
ServerErrorServerError UnexpectedErrorUnexpectedError
ResourceErrorResourceError
NotImplementedNotImplemented
只要出现任何子代码条件,必应就会返回 ServerError。Bing returns ServerError whenever any of the sub-code conditions occur. 如果 HTTP 状态代码为 500,响应就会包含这些错误。The response includes these errors if the HTTP status code is 500.
InvalidRequestInvalidRequest ParameterMissingParameterMissing
ParameterInvalidValueParameterInvalidValue
HttpNotAllowedHttpNotAllowed
已阻止Blocked
只要请求的任何部分无效,必应就会返回 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.

如果错误是 HttpNotAllowed,则 HTTP 状态代码为 410。If the error is HttpNotAllowed, the HTTP status code 410.
RateLimitExceededRateLimitExceeded 只要超过每秒查询数 (QPS) 或每月查询数 (QPM) 配额,必应就会返回 RateLimitExceeded。Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.

如果超过 QPS,必应返回 HTTP 状态代码 429;如果超过 QPM,必应返回 HTTP 状态代码 403。Bing returns HTTP status code 429 if you exceeded QPS and 403 if you exceeded QPM.
InvalidAuthorizationInvalidAuthorization AuthorizationMissingAuthorizationMissing
AuthorizationRedundancyAuthorizationRedundancy
当必应无法验证调用方身份时,必应会返回 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.
InsufficientAuthorizationInsufficientAuthorization AuthorizationDisabledAuthorizationDisabled
AuthorizationExpiredAuthorizationExpired
当调用方无权访问资源时,必应会返回 InsufficientAuthorization。Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. 如果订阅密钥已遭禁用或到期,就会发生此类错误。This can occur if the subscription key has been disabled or has expired.

如果错误是 InsufficientAuthorization,HTTP 状态代码为 403。If the error is InsufficientAuthorization, the HTTP status code is 403.
  • 下表列出了新旧错误代码的对应关系。The following maps the previous error codes to the new codes. 如果之前依赖 v5 错误代码,请相应地更新代码。If you've taken a dependency on v5 error codes, update your code accordingly.
版本 5 codeVersion 5 code 版本 7 代码.子代码Version 7 code.subCode
RequestParameterMissingRequestParameterMissing InvalidRequest.ParameterMissingInvalidRequest.ParameterMissing
RequestParameterInvalidValueRequestParameterInvalidValue InvalidRequest.ParameterInvalidValueInvalidRequest.ParameterInvalidValue
ResourceAccessDeniedResourceAccessDenied InsufficientAuthorizationInsufficientAuthorization
ExceededVolumeExceededVolume RateLimitExceededRateLimitExceeded
ExceededQpsLimitExceededQpsLimit RateLimitExceededRateLimitExceeded
已禁用Disabled InsufficientAuthorization.AuthorizationDisabledInsufficientAuthorization.AuthorizationDisabled
UnexpectedErrorUnexpectedError ServerError.UnexpectedErrorServerError.UnexpectedError
DataSourceErrorsDataSourceErrors ServerError.ResourceErrorServerError.ResourceError
AuthorizationMissingAuthorizationMissing InvalidAuthorization.AuthorizationMissingInvalidAuthorization.AuthorizationMissing
HttpNotAllowedHttpNotAllowed InvalidRequest.HttpNotAllowedInvalidRequest.HttpNotAllowed
UserAgentMissingUserAgentMissing InvalidRequest.ParameterMissingInvalidRequest.ParameterMissing
NotImplementedNotImplemented ServerError.NotImplementedServerError.NotImplemented
InvalidAuthorizationInvalidAuthorization InvalidAuthorizationInvalidAuthorization
InvalidAuthorizationMethodInvalidAuthorizationMethod InvalidAuthorizationInvalidAuthorization
MultipleAuthorizationMethodMultipleAuthorizationMethod InvalidAuthorization.AuthorizationRedundancyInvalidAuthorization.AuthorizationRedundancy
ExpiredAuthorizationTokenExpiredAuthorizationToken InsufficientAuthorization.AuthorizationExpiredInsufficientAuthorization.AuthorizationExpired
InsufficientScopeInsufficientScope InsufficientAuthorizationInsufficientAuthorization
已阻止Blocked InvalidRequest.BlockedInvalidRequest.Blocked

对象变化Object changes

  • 已将 contractualRules 字段添加到 NewsArticle 对象。Added the contractualRules field to the NewsArticle object. contractualRules 字段包含必须遵循的规则列表(例如,文章归属)。The contractualRules field contains a list of rules that you must follow (for example, article attribution). 必须应用 contractualRules 中提供的归属,而不是使用 providerYou must apply the attribution provided in contractualRules instead of using provider. 仅当 Web 搜索 API 响应包含新闻答案时,文章才包含 contractualRulesThe article includes contractualRules only when the Web Search API response contains a News answer.

非重大变化Non-breaking Changes

查询参数Query parameters

  • 已将 Products 添加为可以将 category 查询参数设置为的可取值。Added Products as a possible value that you may set the category query parameter to. 请参阅按市场划分的类别See Categories By Markets.

  • 已添加 SortBy 查询参数,它返回按日期排序的热门主题(最新主题排在最前面)。Added the SortBy query parameter, which returns trending topics sorted by date with the most recent first.

  • 已添加 Since 查询参数,它返回必应在指定 Unix 时间戳期间或之后发现的热门主题。Added the Since query parameter, which returns trending topics that were discovered by Bing on or after the specified Unix epoch timestamp.

对象变化Object changes

  • 已将 mentions 字段添加到 NewsArticle 对象。Added the mentions field to the NewsArticle object. mentions 字段包含在文章中找到的实体(人员或位置)列表。The mentions field contains a list of entities (persons or places) that were found in the article.

  • 已将 video 字段添加到 NewsArticle 对象。Added the video field to the NewsArticle object. video 字段包含与新闻文章相关的视频。The video field contains a video that's related to the news article. 视频要么是可以嵌入的 <iframe>,要么是动作缩略图。The video is either an <iframe> that you can embed or a motion thumbnail.

  • 已将 sort 字段添加到 News 对象。Added the sort field to the News object. sort 字段显示文章排序顺序。The sort field shows the sort order of the articles. 例如,文章按相关性(默认设置)或日期排序。For example, the articles are sorted by relevance (default) or date.

  • 已添加 SortValue 对象,用于定义排序顺序。Added the SortValue object, which defines a sort order. isSelected 字段指明响应是否使用了排序顺序。The isSelected field indicates whether the response used the sort order. 如果为 true,表明响应使用了排序顺序。If true, the response used the sort order. 如果 isSelected 为 false,可以使用 url 字段中的 URL 来请求获取其他排序顺序。If isSelected is false, you can use the URL in the url field to request a different sort order.