將搜尋要求傳送至 Bing 影片搜尋 APISending search requests to the Bing Video Search API

本文說明傳送給 Bing 影片搜尋 API 的要求參數和屬性,以及其傳回的 JSON 回應物件。This article describes the parameters and attributes of requests sent to the Bing Video Search API, as well as the JSON response object it returns.

您必須有具備 Bing 搜尋 API 存取權的認知服務 API 帳戶You must have a Cognitive Services API account with access to the Bing Search APIs. 如果您沒有 Azure 訂用帳戶,可以建立免費帳戶If you don't have an Azure subscription, you can create an account for free. 繼續之前,您需要有啟動免費試用版後所提供的存取金鑰,或是從 Azure 儀表板中取得的付費訂用帳戶金鑰。Before continuing, You will need the access key provided after activating your free trial, or a paid subscription key from your Azure dashboard.

使用 Bing 自動建議 API 建議搜尋字詞Suggest search terms with the Bing Autosuggest API

若您提供使用者可在其中輸入其搜尋字詞的搜尋方塊,請使用 Bing 自動建議 API 來改善使用經驗。If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. API 會根據部分搜尋字詞傳回建議的查詢字串,作為使用者類型。The API returns suggested query strings based on partial search terms as the user types.

在使用者輸入其搜尋字詞之後,會先對此字詞進行 URL 編碼,再設定 q 查詢參數。After the user enters their search term, URL-encode it before setting the q query parameter. 例如,如果使用者輸入 sailing dinghies,請將 q 設定為 sailing+dinghiessailing%20dinghiesFor example, if the user enters sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.

傳送要求Sending a request

若要取得影片搜尋結果,您要將 GET 要求傳送至下列端點:To get Video search results, you'd send a GET request to the following endpoint:

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

要求必須使用 HTTPS 通訊協定。The request must use the HTTPS protocol.

我們建議所有要求均應來自伺服器。We recommend that all requests originate from a server. 隨著用戶端應用程式散佈金鑰,會讓惡意的第三方有更多機會存取該應用程式。Distributing the key as part of a client application provides more opportunity for a malicious third party to access it. 從伺服器進行呼叫,API 未來也就能以同個升級點更新版本。Making calls from a server also provides a single upgrade point for future versions of the API.

要求必須指定 q 查詢參數,其中含有使用者的搜尋字詞。The request must specify the q query parameter, which contains the user's search term. 雖是選擇性,但請在要求中指定 mkt 查詢參數,其可識別您希望從哪個市場取得結果。Although it's optional, the request should also specify the mkt query parameter, which identifies the market where you want the results to come from. 如需選用查詢參數 (例如 pricing) 的清單,請參閱查詢參數For a list of optional query parameters such as pricing, see Query Parameters. 所有查詢參數值均須為 URL 編碼。All query parameter values must be URL encoded.

要求必須指定 Ocp-Apim-Subscription-Key 標頭。The request must specify the Ocp-Apim-Subscription-Key header. 雖然是選擇性的,但我們仍建議使用以下標頭:Although optional, you are encouraged to also specify the following headers:

用戶端 IP 和位置標頭對於傳回位置感知內容很重要。The client IP and location headers are important for returning location aware content.

如需所有要求和回應標頭的清單,請參閱標頭For a list of all request and response headers, see Headers.

範例搜尋要求Example search request

以下顯示搜尋要求,其包含所有建議的查詢參數和標頭。The following shows a search request that includes all the suggested query parameters and headers. 如果這是您第一次呼叫任何的 Bing API,請勿包含用戶端識別碼標頭。If it's your first time calling any of the Bing APIs, don't include the client ID header. 如果您先前已呼叫 Bing API 且 Bing 傳回了使用者和裝置組合的用戶端識別碼,則只要包含用戶端識別碼。Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

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 回應Example JSON response

以下顯示前一個要求的回應。The following shows the response to the previous request. 此範例也示範 Bing 特定回應標頭。The example also shows the Bing-specific response headers.

注意

因為 URL 格式和參數可隨時變更而不會另行通知,因此請依原狀使用所有 URL。Because URL formats and parameters are subject to change without notice, use all URLs as-is. 除非有註明,否則請勿相依於 URL 格式或參數。You should not take dependencies on the URL format or parameters except where noted.

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..."
                    }
                },
                . . .
            ]
        }
    ]
}

後續步驟Next steps

試用 API。Try out the API. 移至影片搜尋 API 測試主控台Go to Video Search API Testing Console.

如需關於取用回應物件的詳細資料,請參閱搜尋網路上的影片 (英文)。For details about consuming the response objects, see Searching the Web for Videos.

如需取得影片的深入解析 (例如相關搜尋) 的詳細資料,請參閱影片深入解析 (英文)。For details about getting insights about a video such as related searches, see Video Insights.

如需社交媒體上發燒影片的詳細資料,請參閱發燒影片 (英文)。For details about videos that are trending on social media, see Trending Videos.