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

视频搜索 API v7 参考

警告

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

视频搜索 API 允许向必应发送搜索查询,并返回与搜索查询相关的视频列表。 本部分提供有关用于请求视频和包含视频的 JSON 响应对象的查询参数和标头的技术详细信息。 有关如何发出请求的示例,请参阅 搜索 Web for Videos

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

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

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

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

注意

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

终结点

若要请求视频,请将 GET 请求发送到以下 URL 之一:

终结点 说明
https://api.cognitive.microsoft.com/bing/v7.0/videos/search 返回与用户搜索查询相关的视频。
https://api.cognitive.microsoft.com/bing/v7.0/videos/details 返回与视频有关的见解(如相关视频)。
https://api.cognitive.microsoft.com/bing/v7.0/videos/trending 基于其他人的搜索请求返回热门视频。 这些视频分为不同的类别。 例如,Top Music Videos。

有关支持热门视频的市场列表,请参阅 趋势视频

对于多服务订阅,必须在 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 必需请求标头。

认知服务中注册此服务时收到的订阅密钥。
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 编码。 有关用于筛选必应返回的视频的查询参数的信息,请参阅 筛选查询参数

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

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

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

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

可以将此参数与参数一起使用 offset 来页结果。 例如,如果用户界面每页显示 20 个视频,则设置为 count 20 和 offset 0 以获取结果的第一页。 对于每个后续页面,递增 offset 20 (,例如 0、20、40) 。

仅对视频搜索 API 使用此参数。 调用趋势视频 API 或 Web 搜索 API 时,请勿指定此参数。
UnsignedShort
id 唯一标识视频的 ID。 Video 对象的videoId字段包含将此参数设置为的 ID。

对于 /videos/search 终结点,请使用此参数来确保指定的视频是必应返回的视频列表中的第一个视频。

对于 /videos/details 终结点,可以使用此参数标识视频以获取见解。
字符串
模块 要请求的见解的逗号分隔列表。 下面是可能的不区分大小写的值。
  • 全部 - 返回所有可用的见解。

  • RelatedVideos - 返回与查询参数指定的 id 视频类似的视频列表。

  • VideoResult - 返回请求见解的视频, (这是在见解请求) 中将查询参数设置为 id 的视频。

如果指定见解且没有数据,则响应对象不包括相关字段。 例如,如果指定 RelatedVideos 且不存在,则响应不包括该 relatedVideos 字段。

尽管不需要用户的查询词,但应始终包含它,因为它有助于提高相关性和结果。

仅在调用 /videos/details 终结点时使用此参数。 调用 /videos 终结点或 Web 搜索 API 时,请勿指定此参数。
字符串
mkt 产生结果的市场。 通常, mkt 是用户发出请求的国家/地区。 但是,如果用户不在必应提供结果的国家/地区,则可能是不同的国家/地区。 市场必须采用语言代码国家/地区代码><>的形式。< 例如,en-US。 字符串不区分大小写。 有关可能的市场值的列表,请参阅 市场代码

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

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

将此参数与参数一起使用 count ,以便对结果进行分页。 例如,如果用户界面每页显示 20 个视频,则设置为 count 20 和 offset 0 以获取结果的第一页。 对于每个后续页面,递增 offset 20 (,例如 0、20、40) 。

多个页面可以在结果中包含一些重叠。 若要防止重复,请参阅 nextOffset

仅对视频搜索 API 使用此参数。 调用趋势视频 API 或 Web 搜索 API 时,请勿指定此参数。
未签名的短
q 用户的搜索查询字符串。 查询字符串不能为空。

查询字符串可能包含 必应高级运算符。 例如,若要将视频限制为特定域,请使用 站点: 运算符。

仅对视频搜索 API 使用此参数。 调用趋势视频 API 时,请勿指定此参数。
字符串
safeSearch 筛选成人内容的视频。 下面是可能的筛选器值。
  • 中等 - 不返回包含成人内容的视频。
  • 严格 - 不返回包含成人内容的视频。
默认级别为“中等”。

注意: 如果 safeSearch 设置为 Off,必应将忽略它并使用 Moderate。

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

注意:如果使用 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 字符处理字符串的信息,请参阅 “命中突出显示”。
字符串

筛选查询参数

以下是可用于筛选必应返回的视频的可选筛选器查询参数。 必须对查询参数进行 URL 编码。

仅将这些查询参数用于视频搜索 API。 调用趋势视频 API 和搜索 API 时,请勿指定这些参数。

名称 Value 类型
方面 按以下纵横比筛选视频:
  • 标准 - 使用标准方面无线电返回视频

  • widescreen - 返回具有宽屏方面无线电的视频
字符串
嵌入式 按以下情况筛选可嵌入的视频:
  • 播放器 - 返回具有可嵌入播放器的视频
字符串
新鲜 按必应发现视频的日期和时间筛选视频。 下面是可能的筛选器值。
  • Day - 返回过去 24 小时内发现的视频

  • 周 - 返回在过去 7 天内发现的视频

  • 月份 - 返回过去 30 天内发现的视频
字符串
定价 按以下定价选项筛选视频:
  • 免费 - 返回免费查看的视频
  • 付费 - 返回需要订阅或付款才能查看的视频
  • 全部 - 不要按定价进行筛选。 指定此值与不指定 pricing 参数相同。
字符串
分辨率 按以下分辨率筛选视频:
  • lowerthan_360p - 返回分辨率低于 360p 分辨率的视频
  • 360p - 返回分辨率为 360p 或更高分辨率的视频
  • 480p - 返回分辨率为 480p 或更高分辨率的视频
  • 720p - 返回分辨率为 720p 或更高分辨率的视频
  • 1080p - 返回分辨率为 1080p 或更高分辨率的视频
  • 全部 - 不要按分辨率进行筛选。 指定此值与不指定 resolution 参数相同。
字符串
videoLength 按以下长度筛选视频:
  • 简短 - 返回小于 5 分钟的视频
  • 中 - 返回介于 5 到 20 分钟(含)之间的视频
  • Long - 返回超过 20 分钟的视频
  • 全部 - 不要按长度进行筛选。 指定此值与不指定 videoLength 参数相同。
字符串

响应对象

注意

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

以下是响应中可以包含的 JSON 响应对象。 如果请求成功,则响应中的顶级对象是 视频 对象(如果终结点为 /videos/search,如果终结点为 /videos/details,则 VideoDetails ;如果终结点为 /videos/ trending,则为 TrendingVideos )。 如果请求失败,则顶级对象为 ErrorResponse 对象。

对象 说明
类别 定义热门视频的类别。
错误 定义发生的错误。
ErrorResponse 请求失败时响应包含的顶级对象。
图像 定义缩略图。
MediaSize 定义媒体内容的大小。
透视表 定义透视段。
发布者 定义发布者或创建者。
查询 定义搜索查询字符串。
Subcategory 定义视频的子类别。
东西 定义视频中显示的主实体的名称。
缩略图 定义缩略图。
磁贴 定义视频磁贴。
TrendingVideos 响应包含的顶级对象,当热门视频请求成功时。
视频 定义与查询相关的视频。
VideoDetails 响应包括的视频见解请求成功时的顶级对象。
视频 响应包含的视频请求成功时的顶级对象。
VideosModule 定义视频列表。

类别

定义热门视频的类别。

元素 说明 类型
子类别 子类别的列表。 例如,Top Music Videos。 Subcategory[]
标题 视频类别的名称。 例如,音乐视频。 字符串

错误

定义已发生的错误。

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

ErrorResponse

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

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

映像

定义缩略图。

名称 Value 类型
contentUrl 源网站上的图像的 URL。 字符串
描述 归因。 字符串
标题 视频说明。 字符串
thumbnailUrl 图像缩略图的 URL。 有关调整图像大小的信息,请参阅 重设图像大小和裁剪缩略图图像 字符串

MediaSize

定义媒体内容的大小。

名称 Value 类型
高度 媒体内容的高度(以像素为单位)。 Integer
width 媒体内容的宽度(以像素为单位)。 Integer

Pivot

定义透视段。

名称 Value 类型
支点 要透视的原始查询中的段。 字符串
建议 透视表的建议查询字符串列表。 查询

Publisher

定义发布者或创建者。

名称 Value 类型
name 发布者或创建者的名称。 字符串

查询

定义搜索查询词。

名称 Value 类型
displayText 查询词的显示版本。 字符串
searchUrl 用于获取相关搜索结果的 URL。 使用 URL 之前,必须根据需要追加查询参数,并包括 Ocp-Apim-Subscription-Key 标头。

如果要在自己的用户界面中显示结果,请使用此 URL。 否则,请使用 webSearchUrl URL。
字符串
text 查询词。 字符串
缩略图 相关图像缩略图的 URL。

该对象仅包含透视建议和相关搜索的此字段。
缩略图
webSearchUrl 将用户带到查询的必应搜索结果页的 URL。 字符串

Subcategory

定义视频的子类别。

元素 说明 类型
瓷砖 子类别中趋势的视频列表。 每个磁贴都包含视频的缩略图和必应查询,该查询返回视频和其他相关视频。 Tile[]
标题 子类别的名称。 例如,本周的病毒视频。 字符串

Thing

定义视频中显示的主实体。

名称 Value 类型
name 视频中显示的主实体的名称。 字符串

缩略图

定义图像缩略图的 URL。

元素 说明 类型
url 图像缩略图的 URL。 字符串

Tile

定义视频磁贴。

元素 说明 类型
image 视频缩略图的 URL。 图像
查询 返回包含主题视频的必应搜索结果页的查询。 例如,如果类别为 Top Music Videos,查询将返回热门音乐视频。 查询

TrendingVideos

响应包含的趋势视频请求成功时的顶级对象。

元素 说明 类型
bannerTiles 最受欢迎的热门视频列表。 Tile[]
类别 分类视频的列表。 例如,音乐视频和病毒视频。 Category[]

视频

定义与查询相关的视频。

注意

由于 URL 格式和参数可能会更改而不通知,因此按原样使用所有 URL。 不应依赖 URL 格式或参数。

名称 Value 类型
allowHttpsEmbed 一个布尔值,该值确定是否可以嵌入视频 (在使用 HTTPS 协议的页面上看到 embedHtml 字段) 。 布尔
allowMobileEmbed 一个布尔值,用于确定是否可以嵌入视频 (在移动设备上看到 embedHtml 字段) 。 如果 true,可以在移动设备上使用 HTML。 布尔
造物主 视频创建者的名称。

仅视频搜索 API 响应包括此字段。
发布者
contentUrl 主机网站上的视频的 URL。 字符串
datePublished 必应发现视频的日期和时间。 日期采用 YYYY-MM-DDTHH:MM:SS 格式。 字符串
描述 视频的简短说明。 字符串
期间 视频的持续时间或长度。 例如,PT2M50S。 有关格式的信息,请参阅 https://en.wikipedia.org/wiki/ISO_8601#Durations 字符串
embedHtml 一个 iframe,可用于在网页中嵌入和运行视频。 字符串
encodingFormat 视频的 mime 类型 (例如 mp4) 。 字符串
高度 视频的高度(以像素为单位)。 Integer
hostPageDisplayUrl 承载视频的网页的显示 URL。

在用户界面中使用此 URL 标识包含视频的主机网页。 URL 格式不正确,不应用于访问主机网页。 若要访问主机网页,请使用 hostPageUrl URL。
字符串
hostPageUrl 托管视频的网页的 URL。

此 URL 和 contentUrl URL 可能相同。
字符串
id 唯一标识视频列表中的此视频的 ID。

只有 Web 搜索 API 响应才包含此字段。 有关如何使用此字段的信息,请参阅 Web 搜索 API 指南中的 “使用排名显示结果 ”。
字符串
isAccessibleForFree 一个布尔值,该值指示视频是否需要付款或付费订阅才能查看。 如果 为 true,则视频是免费的观看。 否则,如果 为 false,则需要付款或订阅。

注意: 如果必应无法确定是否需要付款,则对象可能不包含此字段。

若要确保必应仅返回免费视频,请将 定价 查询参数设置为“免费”。
布尔
isSuperfresh 一个布尔值,指示必应最近是否发现视频。 如果 为 true,则最近发现视频。

若要获取在过去 24 小时内或上周发现的视频,请使用 新鲜度 查询参数。
布尔
mainEntity 视频中显示的主实体的名称。

仅当 SingleDominantVideo (查看视频) 时scenario,该对象才包含此字段。
东西
motionThumbnailUrl 显示视频预览的动画缩略图的 URL。 通常,当用户将鼠标悬停在结果页上的视频缩略图上时,你将使用此 URL 播放视频预览。 字符串
name 视频的名称。 字符串
发行人 发布视频的发布者的列表。 发布者
缩略图 缩略图图像的宽度和高度 () 。thumbnailUrl MediaSize
thumbnailUrl 视频缩略图的 URL。 有关调整图像大小的信息,请参阅 调整图像大小并裁剪缩略图图像 字符串
videoId 唯一标识视频列表中的此视频的 ID。 可以在后续请求中使用 ID 来确保此视频是视频列表中返回的第一个视频。 若要确保视频是列表中的第一个视频,请将请求的 ID 查询参数设置为此 ID。 字符串
viewCount 在源站点上观看视频的次数。 Integer
webSearchUrl 将用户转到必应视频搜索结果并播放视频的 URL。 字符串
width 视频的宽度(以像素为单位)。 Integer

VideoDetails

响应包括视频见解请求成功时的顶级对象。

模块查询参数会影响必应包含在响应中的字段。 如果设置为 modules RelatedVideos,则此对象仅 relatedVideos 包含字段。

名称 Value 类型
_type 类型提示。 字符串
relatedVideos 类似于指定视频的视频列表。 VideosModule
videoResult 请求 (的见解的原始视频是将 ID 查询参数设置为) 的视频。 视频

视频

响应包含的视频请求成功时的顶级对象。

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

名称 Value 类型
_type 类型提示。 字符串
id 唯一标识视频答案的 ID。

有关如何使用此字段的信息,请参阅 Web 搜索 API 指南中的 “使用排名显示结果 ”。
字符串
isFamilyFriendly 一个布尔值,该值确定一个或多个视频是否包含成人内容。 如果视频中没有包含成人内容, isFamilyFriendly 则设置为 true。 否则,如果一个或多个视频包含成人内容, isFamilyFriendly 则设置为 false

如果 为 false,则视频的缩略图图像 (模糊) 像素化。

注意: 只有 Web 搜索 API 响应包括此字段 (视频搜索 API 响应不包括此字段) 。
布尔
nextOffset 将偏移查询参数设置为的 偏移 值。

如果在第一个请求中设置为 offset 0 和 count 30,然后在第二个请求中设置为 offset 30,则第二个响应中的一些结果可能是第一个响应的重复项。

若要防止重复项,请设置为 offsetnextOffset
Integer
pivotSuggestions 对原始查询进行分段的透视列表。 例如,如果查询是 清理 Gutter,必应可能会将查询分段为 “清理 ”和 “装订机”。

清理透视可以包含查询建议,如 Gutter 安装和装订机修复,Gutters 透视可能包含查询建议,如屋顶清洁和窗口清洁。
Pivot[]
场景 反映查询意向的方案。 下面是可能的值。
  • 列表 - 对于有多个与用户意向匹配的视频的情况。

  • SingleDominantVideo - 对于存在与用户请求匹配的单个音乐视频的情况, (Videos 答案将仅包含一个音乐视频) 。 此方案仅适用于音乐视频。

只有 Web 搜索 API 响应才包含此字段。
字符串
totalEstimatedMatches 与查询匹配的估计视频数。 将此数字与 计数偏移 查询参数一起使用,以对结果进行分页。

仅视频搜索 API 响应包括此字段。
Long
value 与查询相关的视频列表。 视频[]
webSearchUrl 请求视频的必应搜索结果的 URL。 字符串

VideosModule

定义视频列表。

元素 说明 类型
value 视频列表。 视频[]

错误代码

下面是请求可能返回的 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
中华人民共和国 中文 zh-CN
波兰 波兰语 pl-PL
葡萄牙 葡萄牙语 pt-PT
菲律宾共和国 英语 en-PH
俄罗斯 俄语 ru-RU
沙特阿拉伯 阿拉伯语 ar-SA
南非 英语 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