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

向必应视频搜索 API 发送搜索请求

警告

2020 年 10 月 30 日,必应搜索 API 从认知服务移动到必应搜索服务。 本文档仅供参考。 有关更新的文档,请参阅必应搜索 API 文档。 关于为必应搜索创建新的 Azure 资源的说明,请参阅通过 Azure 市场创建必应搜索资源

本文介绍了发送到必应视频搜索 API 的请求的参数和属性,以及它返回的 JSON 响应对象。

创建 Azure 资源

通过创建以下 Azure 资源之一开始使用必应视频搜索 API:

必应搜索 v7 资源

  • 在删除资源前,可通过 Azure 门户使用。
  • 使用免费定价层试用该服务,稍后升级到用于生产的付费层。

多服务资源

  • 在删除资源前,可通过 Azure 门户使用。
  • 在多个认知服务中对应用程序使用相同的密钥和终结点。

使用必应自动建议 API 来提供搜索词建议

如果提供供用户输入搜索词的搜索框,请使用必应自动推荐 API 来改进体验。 此 API 根据用户键入的部分搜索词返回建议的查询字符串。

在用户输入搜索词以后,URL 会在设置 q 查询参数之前对搜索词进行编码。 例如,如果用户输入 sailing dinghies,系统会将 q 设置为 sailing+dinghiessailing%20dinghies

发送请求

若要获取视频搜索结果,请向以下终结点发送 GET 请求:

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

请求必须使用 HTTPS 协议。

建议所有请求都源自服务器。 如果将密钥作为客户端应用的一部分进行分发,会让恶意第三方有更多机会来访问密钥。 另外,从服务器执行调用还会提供 API 的将来版本的单一升级点。

请求必须指定包含用户搜索词的 q 查询参数。 尽管是可选的,但请求还应该指定 mkt 查询参数,该参数标识你希望结果来自的市场。 有关可选查询参数(例如 pricing)的列表,请参阅查询参数。 所有查询参数值都必须是 URL 编码。

请求必须指定 Ocp-Apim-Subscription-Key 请求头。 尽管可视需要添加,但仍建议还指定以下请求头:

客户端 IP 和位置请求头对返回位置感知内容非常重要。

有关所有请求头和响应头的列表,请参阅

示例搜索请求

下面显示了包含所有建议的查询参数和标头的搜索请求。 如果是首次调用任何必应 API,请勿添加客户端 ID 请求头。 只有在以前调用过必应 API 且必应针对用户和设备组合返回了客户端 ID 的情况下,才包括客户端 ID。

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies&mkt=en-us HTTP/1.1  
Ocp-Apim-Subscription-Key: 123456789ABCDE  
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)  
X-Search-ClientIP: 999.999.999.999  
X-Search-Location: lat:47.60357;long:-122.3295;re:100  
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>  
Host: api.cognitive.microsoft.com  

示例 JSON 响应

下面的示例展示了对上一请求的响应。 此示例还展示了必应专用响应头。

注意

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

BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D5694...",
    "totalEstimatedMatches" : 1000,
    "value" : [
        {
            "name" : "How to sail - What to Wear for Dinghy Sailing",
            "description" : "An informative video on what to wear when...",
            "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56...",
            "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYWCvh...",
            "datePublished" : "2014-03-04T11:51:53",
            "publisher" : [
                {
                    "name" : "Fabrikam"
                }
            ],
            "creator" : {
                "name" : "Marcus Appel"
            },
            "contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjHZ--g",
            "hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56944...",
            "encodingFormat" : "h264",
            "hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjBZ--g",
            "width" : 1280,
            "height" : 720,
            "duration" : "PT2M47S",
            "motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y6...",
            "embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
            "allowHttpsEmbed" : true,
            "viewCount" : 8743,
            "thumbnail" : {
                "width" : 300,
                "height" : 168
            },
            "videoId" : "6DB795E11A6E3CBAAD636DB795E11E3CBAAD63",
            "allowMobileEmbed" : true,
            "isSuperfresh" : false
        },
        . . .
    ],
    "nextOffset" : 0,
    "pivotSuggestions" : [
        {
            "pivot" : "sailing",
            "suggestions" : []
        },
        {
            "pivot" : "dinghies",
            "suggestions" : [
                {
                    "text" : "Sailing Cruising",
                    "displayText" : "Cruising",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF754...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Sailing..."
                    }
                },
                . . .
            ]
        }
    ]
}

后续步骤

试用 API。 转到视频搜索 API 测试控制台

有关使用响应对象的详细信息,请参阅在网上搜索视频

有关获取关于视频的见解(例如相关搜索)的详细信息,请参阅视频见解

有关社交媒体上的热门视频的详细信息,请参阅热门视频