自訂視頻搜索 API v7 參考Custom Videos Search API v7 reference

自訂視頻搜索 API 允許您向必應發送搜索查詢,並從自訂搜索實例定義的 Web 切片中返回相關視頻的清單。The Custom Videos Search API lets you send a search query to Bing and get back a list of relevant videos from the slice of Web that your Custom Search instance defines. 如需設定自訂搜尋執行個體的相關資訊,請參閱設定您的自訂搜尋體驗For information about configuring a Custom Search instance, see Configure your custom search experience.

有關請求應包含的標頭的資訊,請參閱請求標頭For information about the headers that requests should include, see Request Headers.

有關請求應包含的查詢參數的資訊,請參閱查詢參數For information about the query parameters that requests should include, see Query Parameters.

有關回應可能包含的 JSON 物件的資訊,請參閱回應物件For information about the JSON objects that the response may include, see Response Objects.

有關允許使用和顯示結果的資訊,請參閱必應搜索 API 使用和顯示要求For information about permitted use and display of results, see Bing Search API Use and Display requirements.

注意

因為 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.

端點Endpoints

若要從您的自訂搜尋執行個體要求影像,請將 GET 要求傳送至下列 URL:To request images from your Custom Search instance, send a GET request to the following URL:

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

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

注意

URL 長度上限是 2,048 個字元。The maximum URL length is 2,048 characters. 若要確保您的 URL 長度不超過限制,查詢參數的最大長度應小於 1,500 個字元。To ensure that your URL length does not exceed the limit, the maximum length of your query parameters should be less than 1,500 characters. 如果 URL 超過 2,048 個字元,則伺服器會傳回「404 找不到」。If the URL exceeds 2,048 characters, the server returns 404 Not found.

headersHeaders

以下是要求和回應可能包含的標頭。The following are the headers that a request and response may include.

頁首Header 描述Description
AcceptAccept 選擇性要求標頭。Optional request header.

預設媒體類型為 application/json。The default media type is application/json. 若要指定回應必須使用 JSON-LD,請將 Accept 標頭設定為 application/ld+json。To specify that the response use JSON-LD, set the Accept header to application/ld+json.
Accept-LanguageAccept-Language 選擇性要求標頭。Optional request header.

要用於使用者介面字串語言的逗號分隔清單。A comma-delimited list of languages to use for user interface strings. 清單採用喜好設定的遞減順序。The list is in decreasing order of preference. 如需詳細資訊 (包括預期的格式),請參閱 RFC2616For more information, including expected format, see RFC2616.

此標頭和 setLang 查詢參數彼此互斥 — 請勿同時指定。This header and the setLang query parameter are mutually exclusive—do not specify both.

若您設定此標頭,則您也必須指定 cc 查詢參數。If you set this header, you must also specify the cc query parameter. 若要決定要傳回結果的市場,Bing 會使用它從清單中找到的第一個支援的語言,然後將其與 cc 參數值結合。To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. 如果清單中未包含支援的語言,Bing 會就近尋找支援要求的語言和市場,或將彙總或預設的市場用於結果。If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. 若要判斷 Bing 所使用的市場,請參閱 BingAPIs-Market 標頭。To determine the market that Bing used, see the BingAPIs-Market header.

只有在指定了多種語言時,才需要使用此標頭和 cc 查詢參數。Use this header and the cc query parameter only if you specify multiple languages. 否則,請使用 mktsetLang 查詢參數。Otherwise, use the mkt and setLang query parameters.

使用者介面字串是在使用者介面中作為標籤的字串。A user interface string is a string that's used as a label in a user interface. JSON 回應物件中有幾個使用者介面字串。There are few user interface strings in the JSON response objects. 回應物件中 Bing.com 屬性的任何連結都會套用指定的語言。Any links to Bing.com properties in the response objects apply the specified language.
BingAPIs-MarketBingAPIs-Market 回應標頭。Response header.

要求所使用的市場。The market used by the request. 格式為 <languageCode>-<countryCode>。The form is <languageCode>-<countryCode>. 例如:en-US。For example, en-US.

如果指定的市場未在市場代碼中列出,則此值可能與您在mkt查詢參數中指定的市場不同。If you specify a market that is not listed in Market Codes, this value may differ from the market you specified in the mkt query parameter. 如果為ccAccept 語言指定無法協調的值,則也是如此。The same is true if you specify values for cc and Accept-Language that can't be reconciled.
BingAPIs-TraceIdBingAPIs-TraceId 回應標頭。Response header.

包含要求詳細資料記錄項目的識別碼。The ID of the log entry that contains the details of the request. 發生錯誤時,會擷取這個識別碼。When an error occurs, capture this ID. 如果您無法判定並解決問題,請將此識別碼與其他資訊一併提供給支援小組。If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team.
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 必要的要求標頭。Required request header.

您在認知服務中註冊此服務時收到的訂用帳戶金鑰。The subscription key that you received when you signed up for this service in Cognitive Services.
重試後Retry-After 回應標頭。Response header.

如果超過每秒 (QPS) 或每月 (QPM) 允許的查詢數,則回應包括此標頭。The response includes this header if you exceed the number of queries allowed per second (QPS) or per month (QPM). 標頭包含發送其他請求之前必須等待的秒數。The header contains the number of seconds that you must wait before sending another request.
User-AgentUser-Agent 選擇性要求標頭。Optional request header.

提出要求的使用者代理程式。The user agent originating the request. Bing 會利用使用者代理程式為行動使用者提供最佳體驗。Bing uses the user agent to provide mobile users with an optimized experience. 雖然是選擇性的,但我們仍建議您一律指定此標頭。Although optional, you are encouraged to always specify this header.

「使用者代理程式」應為任何常用瀏覽器所傳送的相同字串。The user-agent should be the same string that any commonly used browser sends. 如需使用者代理程式的相關資訊,請參閱 RFC 2616For information about user agents, see RFC 2616.

以下是使用者代理程式字串的範例。The following are examples of user-agent strings.
  • Windows Phone—Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)Windows Phone—Mozilla/5.0 (compatible; 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; like Gecko) Version/4.0 Mobile Safari/533.1Android—Mozilla/5.0 (Linux; U; Android 2.3.5; en-us; SCH-I500 Build/GINGERBREAD) AppleWebKit/533.1 (KHTML; like Gecko) Version/4.0 Mobile Safari/533.1

  • iPhone—Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/536.26 (KHTML; like Gecko) Mobile/10B142 iPhone4;1 BingWeb/3.03.1428.20120423iPhone—Mozilla/5.0 (iPhone; CPU iPhone OS 6_1 like Mac OS X) AppleWebKit/536.26 (KHTML; like 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) like GeckoPC—Mozilla/5.0 (Windows NT 6.3; WOW64; Trident/7.0; Touch; rv:11.0) like Gecko

  • iPad—Mozilla/5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53iPad—Mozilla/5.0 (iPad; CPU OS 7_0 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53
X-MSEdge-ClientIDX-MSEdge-ClientID 選擇性要求和回應標頭。Optional request and response header.

Bing 使用此標頭在 Bing API 所有呼叫之間為使用者提供一致的行為。Bing uses this header to provide users with consistent behavior across Bing API calls. Bing 經常推出新功能和改善項目,且會以用戶端識別碼作為不同測試版指派流量的金鑰。Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. 如果在多個要求中,未讓使用者使用相同的用戶端識別碼,Bing 可能會將使用者指派至多個衝突的測試版。If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. 若指派給多個衝突的測試版,可能會導致使用者體驗不一致。Being assigned to multiple conflicting flights can lead to an inconsistent user experience. 例如若第二個要求與第一個要求指派的測試版不同,可能會產生意料外的體驗。For example, if the second request has a different flight assignment than the first, the experience may be unexpected. 此外,Bing 可以使用用戶端識別碼將 Web 結果調整為該用戶端識別碼的搜尋記錄,為使用者提供更豐富的體驗。Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user.

Bing 也會使用此標頭分析用戶端識別碼產生的活動,協助改善結果的順位。Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. 相關性改進功能有助於 Bing API 提供更高品質的結果,進而為 API 取用者提供更高的點擊率。The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer.

重要事項: 雖然是選擇性的,但您仍應將此標頭視為必要項目。IMPORTANT: Although optional, you should consider this header required. 為相同的使用者和裝置組合跨多個要求保存用戶端識別碼,可讓 1) API 取用者獲得一致的使用者體驗,以及 2) 透過 Bing API 更理想的結果品質獲得較高的點擊率。Persisting the client ID across multiple requests for the same end user and device combination enables 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs.

以下是適用於此標頭的基本使用規則。The following are the basic usage rules that apply to this header.
  • 在裝置上使用您應用程式的每個使用者必須具有 Bing 產生的唯一用戶端識別碼。Each user that uses your application on the device must have a unique, Bing generated client ID.

    如果您未在要求中包含此標頭,Bing 會產生一個識別碼,並於 X-MSEdge-ClientID 回應標頭傳回該識別碼。If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. 不應在要求中包含此標頭的唯一時機是使用者初次在該裝置上使用您的應用程式時。The only time that you should NOT include this header in a request is the first time the user uses your app on that device.

  • 注意: 您必須確保此用戶端識別碼不能連結到任何可辨識身分的使用者帳戶資訊。ATTENTION: You must ensure that this Client ID is not linkable to any authenticatable user account information.

  • 您的應用程式每次為該裝置上的該名使用者提出 Bing API 請求時,均需使用此用戶端識別碼。Use the client ID for each Bing API request that your app makes for this user on the device.

  • 保存用戶端識別碼。Persist the client ID. 若要在瀏覽器應用程式中保存識別碼,請使用永續性的 HTTP Cookie,以確保在所有工作階段均使用該識別碼。To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. 請勿使用工作階段 Cookie。Do not use a session cookie. 若為其他應用程式 (例如行動裝置應用程式),請使用裝置本身的永久儲存裝置保存識別碼。For other apps such as mobile apps, use the device's persistent storage to persist the ID.

    使用者下次在該裝置上使用您的應用程式時,會取得您保存的用戶端識別碼。The next time the user uses your app on that device, get the client ID that you persisted.

注意: Bing 回應不一定會包含此標頭。NOTE: Bing responses may or may not include this header. 如果回應包含此標頭,請擷取用戶端識別碼,並將其用於該裝置上使用者的所有後續 Bing 要求。If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device.

注意: 如果您包含 X-MSEdge-ClientID,則不得在要求中加入 Cookie。NOTE: If you include the X-MSEdge-ClientID, you must not include cookies in the request.
X-MSEdge-ClientIPX-MSEdge-ClientIP 選擇性要求標頭。Optional request header.

用戶端裝置的 IPv4 或 IPv6 位址。The IPv4 or IPv6 address of the client device. 此 IP 位址可用來探索使用者的位置。The IP address is used to discover the user's location. Bing 會使用位置資訊來判斷安全搜尋行為。Bing uses the location information to determine safe search behavior.

注意: 雖然是選擇性的,但我們仍建議您一律指定此標頭和 X-Search-Location 標頭。NOTE: Although optional, you are encouraged to always specify this header and the X-Search-Location header.

請勿混淆位址 (例如,藉由將最後一個八位元變更為 0)。Do not obfuscate the address (for example, by changing the last octet to 0). 混淆位址會導致位置不在裝置的實際位置附近,這可能會造成 Bing 產生錯誤結果。Obfuscating the address results in the location not being anywhere near the device's actual location, which may result in Bing serving erroneous results.
X-Search-LocationX-Search-Location 選擇性要求標頭。Optional request header.

以分號分隔的索引鍵/值組清單,用以說明用戶端的地理位置。A semicolon-delimited list of key/value pairs that describe the client's geographical location. Bing 會使用位置資訊來判斷安全的搜尋行為,以及傳回相關的區域內容。Bing uses the location information to determine safe search behavior and to return relevant local content. 請將索引鍵/值組指定為 <key>:<value>。Specify the key/value pair as <key>:<value>. 以下是您用來指定使用者位置的索引鍵。The following are the keys that you use to specify the user's location.

  • lat — 必要項目。lat—Required. 用戶端所在位置的緯度,以度為單位。The latitude of the client's location, in degrees. 緯度必須大於或等於 -90.0 且小於或等於 +90.0。The latitude must be greater than or equal to -90.0 and less than or equal to +90.0. 負數值表示南半球的緯度,正數值表示北半球的緯度。Negative values indicate southern latitudes and positive values indicate northern latitudes.

  • long — 必要項目。long—Required. 用戶端所在位置的經度,以度為單位。The longitude of the client's location, in degrees. 經度必須大於或等於 -180.0 且小於或等於 +180.0。The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. 負數值表示東半球的經度,正數值表示西半球的經度。Negative values indicate western longitudes and positive values indicate eastern longitudes.

  • re — 必要項目。re—Required. 以公尺為單位的半徑,指定座標的水平精確度。The radius, in meters, which specifies the horizontal accuracy of the coordinates. 請傳遞裝置的位置服務所傳回的值。Pass the value returned by the device's location service. 常見的值可能是 22m (用於 GPS/Wi-Fi)、380m (用於無線訊號基地台三角網定位),和 18,000m (用於保留 IP 查閱)。Typical values might be 22m for GPS/Wi-Fi, 380m for cell tower triangulation, and 18,000m for reverse IP lookup.

  • ts — 選擇性。ts—Optional. 用戶端位於該位置的 UTC UNIX 時間戳記。The UTC UNIX timestamp of when the client was at the location. (UNIX 時間戳記是自 1970 年 1 月 1 日起經過的秒數)。(The UNIX timestamp is the number of seconds since January 1, 1970.)

  • head — 選擇性。head—Optional. 用戶端移動的相對走向或方向。The client's relative heading or direction of travel. 指定 0 到 360 度的的移動方向為,計算相對於正北的順時針偏移角度。Specify the direction of travel as degrees from 0 through 360, counting clockwise relative to true north. 只有在 sp 索引鍵為非零值時,才需要指定此索引鍵。Specify this key only if the sp key is nonzero.

  • sp — 選擇性。sp—Optional. 用戶端裝置移動的水平速度,以公尺/秒為單位。The horizontal velocity (speed), in meters per second, that the client device is traveling.

  • alt — 選擇性。alt—Optional. 用戶端裝置的海拔高度,以公尺為單位。The altitude of the client device, in meters.

  • are — 選擇性。are—Optional. 以公尺為單位的半徑,指定座標的垂直精確度。The radius, in meters, that specifies the vertical accuracy of the coordinates. 只有在指定了 alt 索引鍵時,才需要指定此索引鍵。Specify this key only if you specify the alt key.

  • —可選。disp—Optional. 使用者的地理位置在表單中,disp:<城市,州>。The user’s geographic location in the form, disp:<City, State>. 例如,disp:西雅圖,華盛頓。For example, disp:Seattle, Washington. 這是使用 lat/long 鍵指定的使用者位置的顯示文本版本。This is the display text version of the user’s location that you specified using the lat/long keys. 如果此值與 lat/long 座標衝突,必應使用 disp 值作為使用者的位置。If this value conflicts with the lat/long coordinates, Bing uses the disp value as the user's location.

注: 如果查詢包含位置,必應將忽略此標頭。NOTE: Bing ignores this header if the query includes a location. 例如,如果此標頭反映使用者的位置為三藩市,但查詢是西雅圖餐廳,必應返回位於華盛頓州西雅圖的餐廳。For example, if this header reflects the user’s location as San Francisco, but the query is restaurants seattle, Bing returns restaurants located in Seattle, Washington.

注意: 雖然有很多索引鍵是選擇性的,但您提供的資訊愈詳細,位置結果就愈精確。NOTE: Although many of the keys are optional, the more information that you provide, the more accurate the location results are.

注意: 使用者的地理位置雖然是選擇性的,但建議您一律加以指定。NOTE: Although optional, you are encouraged to always specify the user's geographical location. 如果用戶端的 IP 位址未精確反映使用者的實體位置 (例如,如果用戶端使用 VPN),提供位置就益發重要。Providing the location is especially important if the client's IP address does not accurately reflect the user's physical location (for example, if the client uses VPN). 為獲得最佳結果,應包括此標頭和 X-搜索-用戶端 IP 標頭,但至少應包括此標頭。For optimal results, you should include this header and the X-Search-ClientIP header, but at a minimum, you should include this header.

注意

請記住,使用條款會要求您遵守所有適用法規,包括使用這些標頭的相關法規。Remember that the Terms of Use require compliance with all applicable laws, including regarding use of these headers. 例如,特定轄區 (例如歐洲) 會要求必須先取得使用者同意,才可在使用者裝置上放置特定追蹤裝置。For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.

查詢參數Query parameters

下面列出了請求可能包含的查詢參數。The following lists the query parameters that a request may include. 請參閱必要參數的必要資料行。See the Required column for required parameters. 您必須為查詢參數值進行 URL 編碼。You must URL encode the query parameter values. 有關用於篩選必應返回的視頻的查詢參數的資訊,請參閱篩選器查詢參數For information about query parameters used to filter the videos that Bing returns, see Filter Query Parameters.

名稱Name Value 類型Type 必要Required
cccc 產生結果的國家/地區所具備的 2 字元國碼 (地區碼)。A 2-character country code of the country where the results come from. 有關可能值的清單,請參閱市場代碼For a list of possible values, see Market Codes.

若您設定此參數,則您也必須指定 Accept-Language 標頭。If you set this parameter, you must also specify the Accept-Language header. 必應使用它在指定語言中找到的第一種受支援的語言,並將其與國家/地區代碼相結合,以確定要返回結果的市場。Bing uses the first supported language it finds in the specified languages and combines it with the country code to determine the market to return results for. 如果語言清單中未包含支援的語言,Bing 會就近尋找支援要求的語言和市場。If the languages list does not include a supported language, Bing finds the closest language and market that supports the request. 或者,必應可能使用聚合或預設市場來進行結果。Or, Bing may use an aggregated or default market for the results.

僅當指定多種語言時,Accept-Language才使用此查詢參數和標頭。Use this query parameter and the Accept-Language header only if you specify multiple languages. 否則,應使用 和mkt``setLang查詢參數。Otherwise, you should use the mkt and setLang query parameters.

此參數和 mkt 查詢參數彼此互斥 — 請勿同時指定。This parameter and the mkt query parameter are mutually exclusive—do not specify both.
StringString No
countcount 回應中要返回的視頻數。The number of videos to return in the response. 傳遞的實際數目可能小於所要求的數目。The actual number delivered may be less than requested. 預設值為 35。The default is 35. 最大值為 105。The maximum is 105.

您可以使用此參數以及參數offset來創建頁面結果。You may use this parameter along with the offset parameter to page results. 例如,如果使用者介面每頁顯示 20 個視頻,設置為count20offset和 0 以獲得第一頁的結果。For example, if your user interface presents 20 videos per page, set count to 20 and offset to 0 to get the first page of results. 對於每個後續頁面,遞offset增 20(例如,0、20、40)。For each subsequent page, increment offset by 20 (for example, 0, 20, 40).
UnsignedShortUnsignedShort No
自訂配置customConfig 標識自訂搜索實例的唯一識別碼。Unique identifier that identifies your custom search instance.

StringString Yes
Idid 唯一標識視頻的 ID。An ID that uniquely identifies a video. "視頻"物件的videoId欄位包含您為此參數設置到的 ID。The Video object's videoId field contains the ID that you set this parameter to.

對於 /videos/搜索終結點,使用此參數可確保指定的視頻是必應返回的視頻清單中的第一個視頻。For the /videos/search endpoint, you use this parameter to ensure that the specified video is the first video in the list of videos that Bing returns.

對於 /videos/詳細資訊終結點,使用此參數標識視頻以獲得見解。For the /videos/details endpoint, you use this parameter to identify the video to get insights of.
StringString No
mktmkt 產生結果的市場。The market where the results come from. 通常,mkt使用者發出請求的國家/地區。Typically, mkt is the country where the user is making the request from. 但是,如果使用者不位於必應交付結果的國家/地區,則可能是另一個國家/地區。However, it could be a different country if the user is not located in a country where Bing delivers results. 市場必須在格式<>-<語言代碼國家代碼。>The market must be in the form <language code>-<country code>. 例如:en-US。For example, en-US. 字串不區分大小寫。The string is case insensitive. 如需可能的市場值清單,請參閱市場代碼For a list of possible market values, see Market Codes.

注: 如果已知,則鼓勵您始終指定市場。NOTE: If known, you are encouraged to always specify the market. 指定市場可協助 Bing 路由傳送要求,並傳回適當的最佳回應。Specifying the market helps Bing route the request and return an appropriate and optimal response. 如果您指定的市場未在市場代碼中列出,必應使用基於內部映射的最佳市場代碼,該代碼可能會更改。If you specify a market that is not listed in Market Codes, Bing uses a best fit market code based on an internal mapping that is subject to change.

此參數和 cc 查詢參數彼此互斥 — 請勿同時指定。This parameter and the cc query parameter are mutually exclusive—do not specify both.
StringString No
offsetoffset 零偏移,指示在返回視頻之前要跳過的視頻數。The zero-based offset that indicates the number of videos to skip before returning videos. 預設值是 0。The default is 0. 偏移量應小於 (總估計匹配項 - count)。The offset should be less than (totalEstimatedMatches - count).

使用此參數以及該count參數可創建頁面結果。Use this parameter along with the count parameter to page results. 例如,如果使用者介面每頁顯示 20 個視頻,則count設置為 20offset和 0 以獲取第一頁的結果。For example, if your user interface displays 20 videos per page, set count to 20 and offset to 0 to get the first page of results. 對於每個後續頁面,遞offset增 20(例如,0、20、40)。For each subsequent page, increment offset by 20 (for example, 0, 20, 40).

多個頁面可以在結果中包含一些重疊。It is possible for multiple pages to include some overlap in results. 要防止重複,請參閱下一個偏移To prevent duplicates, see nextOffset.
未簽名短Unsigned Short No
qq 使用者的搜索查詢字串。The user's search query string. 查詢字串不能為空。The query string cannot be empty.

注: 查詢字串不能包含必應高級運算子NOTE: The query string must not contain Bing Advanced Operators. 包括它們可能會對自訂搜索體驗產生負面影響。Including them may adversely affect the custom search experience.
StringString Yes
safeSearchsafeSearch 過濾成人內容的視頻。Filter videos for adult content. 以下是可能的篩選器值。The following are the possible filter values.
  • 中—度不包括包含成人內容的視頻。Moderate—Does not include videos with adult content.
  • 嚴格—不包括包含成人內容的視頻。Strict—Does not include videos with adult content.
預設值為「中度」。The default is Moderate.

注: 如果safeSearch設置為"關閉",必應將忽略它並使用"適度"。NOTE: If safeSearch is set to Off, Bing ignores it and uses Moderate.

注: 如果請求來自必應的成人政策要求safeSearch設置為"嚴格"的市場,必應忽略safeSearch該值並使用"嚴格"。NOTE: If the request comes from a market that Bing's adult policy requires safeSearch be set to Strict, Bing ignores the safeSearch value and uses Strict.

注意: 如果您使用 site: 查詢運算子,則無論 safeSearch 查詢參數設定為何,回應都有可能包含成人內容。NOTE: If you use the site: query operator, there is the chance that the response may contain adult content regardless of what the safeSearch query parameter is set to. 只有在您了解網站上的內容,而且您的案例支援成人內容的可能性時,才可使用 site:Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.
StringString No
setLangsetLang 用於使用者介面字串的語言。The language to use for user interface strings. 您可以使用 2 個字母或 4 個字母的代碼指定語言。You may specify the language using either a 2-letter or 4-letter code. 最好使用 4 個字母代碼。Using 4-letter codes is preferred.

有關支援的語言代碼的清單,請參閱必應支援的語言For a list of supported language codes, see Bing supported languages.

如果setlang包含有效的 2 個字母中性區域性代碼 (fr) 或有效的 4 個字母特定區域性代碼 (fr-ca), 必應載入當地語系化字串。Bing loads the localized strings if setlang contains a valid 2-letter neutral culture code (fr) or a valid 4-letter specific culture code (fr-ca). 例如,對於fr-ca, 必應載入fr中性區域性代碼字串。For example, for fr-ca, Bing loads the fr neutral culture code strings.

如果setlang無效(例如 ,zh) 或必應不支援該語言(例如,af、af-na),af則必af-na應預設為en( 英語)。If setlang is not valid (for example, zh) or Bing doesn’t support the language (for example, af, af-na), Bing defaults to en (English).

要指定 2 個字母的代碼,請為此參數設置為 ISO 639-1 語言代碼。To specify the 2-letter code, set this parameter to an ISO 639-1 language code.

要指定 4 個字母的代碼,請使用 iSO 639-1 語言代碼(中性區域性)的表單-<國家/地區>,<國家/地區/地區>是 ISO 3166 國家/區域(特定區域性)代碼。To specify the 4-letter code, use the form -<country/region> where is an ISO 639-1 language code (neutral culture) and <country/region> is an ISO 3166 country/region (specific culture) code. 例如,為美國英語使用en-US。For example, use en-US for United States English.

語言雖然是選擇性的,但您應一律加以指定。Although optional, you should always specify the language. 一般而言,除非使用者想要以不同的語言顯示使用者介面字串,否則您都會將 setLang 設定為 mkt 所指定的相同語言。Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.

此參數和"接受語言"標頭是互斥的,不指定兩者。This parameter and the Accept-Language header are mutually exclusive—do not specify both.

使用者介面字串是在使用者介面中作為標籤的字串。A user interface string is a string that's used as a label in a user interface. JSON 回應物件中有幾個使用者介面字串。There are few user interface strings in the JSON response objects. 同樣地,回應物件中 Bing.com 屬性的任何連結都會套用指定的語言。Also, any links to Bing.com properties in the response objects apply the specified language.
StringString No

篩選器查詢參數Filter query parameters

以下是可選的篩選器查詢參數,可用於篩選必應返回的視頻。The following are the optional filter query parameters that you can use to filter the videos that Bing returns. 您必須對查詢參數進行 URL 編碼。You must URL encode the query parameters.

名稱Name Value 類型Type
新鮮freshness 按必應發現視頻的日期和時間篩選視頻。Filter videos by the date and time that Bing discovered the video. 以下是可能的篩選器值。The following are the possible filter values.
  • 在過去—24 小時內發現的日返回視頻Day—Return videos discovered within the last 24 hours

  • 過去—7 天內發現的周返回視頻Week—Return videos discovered within the last 7 days

  • 在過去—30 天內發現的月返回視頻Month—Return videos discovered within the last 30 days
  • 去年—發現的年份返回圖像Year—Return images discovered within the last year
  • 2017-06-15.2018-06-15—返回在指定日期範圍內發現的圖像2017-06-15..2018-06-15—Return images discovered within the specified range of dates
StringString No
定價pricing 按以下定價選項篩選視頻:Filter videos by the following pricing options:
  • 免費—返回視頻,可免費觀看Free—Return videos that are free to view
  • 需要—訂閱或付款才能查看的付費退貨視頻Paid—Return videos that require a subscription or payment to view
  • 所有—不要按定價進行篩選。All—Do not filter by pricing. 指定此值與不指定參數pricing相同。Specifying this value is the same as not specifying the pricing parameter.
StringString
解析度resolution 按以下解析度篩選視頻:Filter videos by the following resolutions:
  • 480p—返回解析度為 480p 或更高的視頻480p—Return videos with a 480p or higher resolution
  • 720p—返回解析度為 720p 或更高的視頻720p—Return videos with a 720p or higher resolution
  • 1080p—返回視頻,解析度為 1080p 或更高1080p—Return videos with a 1080p or higher resolution
  • 所有—不能按解析度進行篩選。All—Do not filter by resolution. 指定此值與不指定參數resolution相同。Specifying this value is the same as not specifying the resolution parameter.
StringString
視頻長度videoLength 按以下長度篩選視頻:Filter videos by the following lengths:
  • 少於—5 分鐘的短返回視頻Short—Return videos that are less than 5 minutes
  • 5—到 20 分鐘的中回視頻,包括Medium—Return videos that are between 5 and 20 minutes, inclusive
  • 長—返回視頻超過 20 分鐘Long—Return videos that are longer than 20 minutes
  • 所有—內容均不按長度進行篩選。All—Do not filter by length. 指定此值與不指定參數videoLength相同。Specifying this value is the same as not specifying the videoLength parameter.
StringString

回應物件Response objects

注意

為了遵守新的歐盟版權指令在法國,必應網路,新聞,視頻,圖像和所有自訂搜索API必須省略某些歐盟新聞來源為法國使用者的某些內容。To comply with the new EU Copyright Directive in France, the Bing Web, News, Video, Image and all Custom Search APIs must omit some content from certain EU News sources for French users. 刪除的內容可能包括縮略圖圖像和視頻、視頻預覽以及這些源搜尋結果附帶的程式碼片段。The removed content may include thumbnail images and videos, video previews, and snippets which accompany search results from these sources. 因此,必應 API 可能會為法國使用者提供更少的結果,包括縮略圖圖像和視頻、視頻預覽和片段。As a consequence, the Bing APIs may serve fewer results with thumbnail images and videos, video previews, and snippets to French users.

以下是回應可能包含的 JSON 回應物件。The following are the JSON response objects that the response may include. 如果請求成功,回應中的頂級物件是"視頻"物件。If the request succeeds, the top-level object in the response is the Videos object. 如果要求失敗,則最上層的物件是 ErrorResponse 物件。If the request fails, the top-level object is the ErrorResponse object.

ObjectObject 描述Description
錯誤Error 定義發生的錯誤。Defines an error that occurred.
ErrorResponseErrorResponse 要求失敗時,回應包含的最上層物件。The top-level object that the response includes when the request fails.
MediaSizeMediaSize 定義媒體內容的大小。Defines the size of the media content.
樞紐Pivot 定義樞軸段。Defines the pivot segment.
出版商Publisher 定義發行者或建立者。Defines a publisher or creator.
查詢Query 定義搜索查詢字串。Defines a search query string.
事情Thing 定義視頻中顯示的主要實體的名稱。Defines the name of the main entity shown in the video.
縮圖Thumbnail 定義縮略圖圖像。Defines a thumbnail image.
視頻Video 定義與查詢相關的視頻。Defines a video that is relevant to the query.
影片Videos 當視頻請求成功時,回應包括的頂級物件。The top-level object that the response includes when the video request succeeds.

錯誤Error

定義發生的錯誤。Defines the error that occurred.

元素Element 描述Description 類型Type
codecode 識別錯誤類別的錯誤碼。The error code that identifies the category of error. 如需可能的代碼清單,請參閱錯誤碼For a list of possible codes, see Error Codes. StringString
messagemessage 錯誤的描述。A description of the error. StringString
moreDetailsmoreDetails 提供其他錯誤相關資訊的描述。A description that provides additional information about the error. StringString
parameterparameter 要求中導致錯誤的查詢參數。The query parameter in the request that caused the error. StringString
subCodesubCode 識別錯誤的錯誤碼。The error code that identifies the error. 例如,如果 code是 InvalidRequest,則 subCode 可能是 ParameterInvalid 或 ParameterInvalidValue。For example, if code is InvalidRequest, subCode may be ParameterInvalid or ParameterInvalidValue. StringString
valuevalue 非有效的查詢參數值。The query parameter's value that was not valid. StringString

ErrorResponseErrorResponse

要求失敗時,回應包含的最上層物件。The top-level object that the response includes when the request fails.

名稱Name Value 類型Type
_type_type 類型提示。Type hint. StringString
errorserrors 說明要求失敗原因的錯誤清單。A list of errors that describe the reasons why the request failed. 錯誤 Error[]

MediaSizeMediaSize

定義媒體內容的大小。Defines the size of the media content.

名稱Name Value 類型Type
heightheight 媒體內容的高度(以圖元為單位)。The height of the media content, in pixels. 整數 Integer
widthwidth 媒體內容的寬度(以圖元為單位)。The width of the media content, in pixels. 整數 Integer

樞紐Pivot

定義樞軸段。Defines the pivot segment.

名稱Name Value 類型Type
支點pivot 從原始查詢到透視的段。The segment from the original query to pivot on. StringString
建議suggestions 資料透視的建議查詢字串的清單。A list of suggested query strings for the pivot. 查詢Query

發行者Publisher

定義發行者或建立者。Defines a publisher or creator.

名稱Name Value 類型Type
NAMEname 發行者或建立者的名稱。The publisher's or creator's name. StringString

查詢Query

定義搜索查詢詞。Defines a search query term.

名稱Name Value 類型Type
顯示文本displayText 查詢術語的顯示版本。The display version of the query term. StringString
搜索UrlsearchUrl 用於獲取相關搜尋結果的 URL。The URL that you use to get the results of the related search. 在使用 URL 之前,必須根據需要新增查詢參數,並包括Ocp-Apim-訂閱金鑰標頭。Before using the URL, you must append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header.

如果要在自己的使用者介面中顯示結果,請使用此 URL。Use this URL if you're displaying the results in your own user interface. 否則,webSearchUrl請使用 URL。Otherwise, use the webSearchUrl URL.
StringString
文字text 查詢術語。The query term. StringString
縮略 圖thumbnail 相關圖像縮略圖的 URL。The URL to a thumbnail of a related image.

該物件僅包括此欄位,用於透視建議和相關搜索。The object includes this field only for pivot suggestions and related searches.
縮圖Thumbnail
webSearchUrlwebSearchUrl 將使用者帶到查詢的必應搜尋結果頁的 URL。The URL that takes the user to the Bing search results page for the query. StringString

項目Thing

定義視頻中顯示的主要實體。Defines the main entity shown in the video.

名稱Name Value 類型Type
NAMEname 視頻中顯示的主要實體的名稱。The name of the main entity shown in the video. StringString

縮圖Thumbnail

定義圖像縮略圖的 URL。Defines the URL to a thumbnail of an image.

元素Element 描述Description 類型Type
urlurl 圖像縮略圖的 URL。The URL to a thumbnail of an image. StringString

影片Video

定義與查詢相關的視頻。Defines a video that is relevant to the query.

注意

由於 URL 格式和參數可能會更改,恕不另行通知,因此應使用所有 URL。Because the URL format 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.

名稱Name Value 類型Type
允許 HttpsEmbedallowHttpsEmbed 布林值,用於確定是否可以在使用 HTTPS 協定的頁面上嵌入embedHtml視頻(請參閱欄位)。A Boolean value that determines whether you may embed the video (see the embedHtml field) on pages that use the HTTPS protocol. BooleanBoolean
允許移動嵌入allowMobileEmbed 布林值,用於確定是否可以將視頻嵌入行動裝置上(請參閱embedHtml欄位)。A Boolean value that determines whether you may embed the video (see the embedHtml field) on a mobile device. 如果true,則可以在行動裝置上使用 HTML。If true, you may use the HTML on a mobile device. BooleanBoolean
創造者creator 視頻建立者的名稱。The name of the video's creator.

僅視頻搜索 API 回應包括此欄位。Only Video Search API responses include this field.
出版商Publisher
contentUrlcontentUrl 主機網站上視頻的 URL。The URL to the video on the host website. StringString
發佈日期datePublished 必應發現視頻的日期和時間。The date and time that Bing discovered the video. 日期以 YYYY-MM-DDTHH:MM:SS 格式。The date is in the format, YYYY-MM-DDTHH:MM:SS. StringString
描述description 視頻的簡短描述。A short description of the video. StringString
時間duration 視頻的持續時間或長度。The video's duration or length. 例如,PT2M50S。For example, PT2M50S. 有關格式的資訊,請參閱https://en.wikipedia.org/wiki/ISO_8601#DurationsFor information about the format, see https://en.wikipedia.org/wiki/ISO_8601#Durations. StringString
嵌入HtmlembedHtml 一個 iframe,允許您在網頁中嵌入和運行視頻。An iframe that lets you embed and run the video in your webpage. StringString
編碼格式encodingFormat 視頻的默劇類型(例如 mp4)。The video's mime type (for example, mp4). StringString
heightheight 視頻的高度(以圖元為單位)。The height of the video, in pixels. 整數 Integer
主機頁面顯示UrlhostPageDisplayUrl 承載視頻的網頁的顯示 URL。The display URL of the webpage that hosts the video.

在使用者介面中使用此 URL 來標識包含視頻的主機網頁。Use this URL in your user interface to identify the host webpage that contains the video. URL 格式不正確,不應用於訪問主機網頁。The URL is not a well-formed and should not be used to access the host webpage. 要訪問主機網頁,hostPageUrl請使用 URL。To access the host webpage, use the hostPageUrl URL.
StringString
主機PageUrlhostPageUrl 承載視頻的網頁的 URL。The URL to the webpage that hosts the video.

此 URLcontentUrl和 URL 可能是同一 URL。This URL and contentUrl URL may be the same URL.
StringString
可免費訪問isAccessibleForFree 布林值,指示視頻是否需要付費還是付費訂閱才能查看。A Boolean value that indicates whether the video requires payment or a paid subscription to view. 如果為 true, 則視頻可以自由觀看。If true, the video is free to watch. 否則,如果為 false, 則需要付款或訂閱。Otherwise, if false, a payment or subscription is required.

注: 如果必應無法確定是否需要付款,則物件可能不包括此欄位。NOTE: If Bing is unable to determine whether payment is required, the object may not include this field.

為確保必應僅返回免費視頻,請將定價查詢參數設置為"免費"。To ensure that Bing returns only free videos, set the pricing query parameter to Free.
BooleanBoolean
是超級新鮮isSuperfresh 一個布林值,指示視頻是否最近由必應發現。A Boolean value that indicates whether the video was recently discovered by Bing. 如果是真的,視頻是最近發現的。If true, the video was recently discovered.

要獲取在過去 24 小時內或上周內發現的視頻,請使用新鮮度查詢參數。To get videos discovered within the last 24 hours or the last week, use the freshness query parameter.
BooleanBoolean
主實體mainEntity 視頻中顯示的主要實體的名稱。The name of the main entity shown in the video.

僅當是單一主顯視頻scenario時,該物件才包括此欄位(請參閱視頻)。The object includes this field only when scenario is SingleDominantVideo (see Videos).
事情Thing
運動縮略圖motionThumbnailUrl 顯示視頻預覽的動畫縮略圖的 URL。The URL to an animated thumbnail that shows a preview of the video. 通常,當使用者在結果頁面上的縮略圖上滑鼠時,使用此 URL 可以播放視頻預覽。Typically, you would use this URL to play a preview of the video when the user mouses over the thumbnail of the video on your results page. StringString
名字name 影片的名稱。The name of the video. StringString
出版商publisher 發佈視頻的發行者的清單。A list of the publishers that published the video. 出版商Publisher
縮略 圖thumbnail 縮略圖圖像的寬度和高度(請參閱thumbnailUrl)。The width and height of the thumbnail image (see thumbnailUrl). MediaSizeMediaSize
縮略圖UrlthumbnailUrl 視頻縮略圖圖像的 URL。The URL to a thumbnail image of the video. 有關調整圖像大小的資訊,請參閱調整縮略圖和裁剪縮略圖圖像For information about resizing the image, see Resize and crop thumbnail images. StringString
videoIdvideoId 在視頻清單中唯一標識此視頻的 ID。An ID that uniquely identifies this video in the list of videos. 您可以在後續請求中使用 ID,以確保此視頻是視頻清單中返回的第一個視頻。You can use the ID in a subsequent request to ensure that this video is the first video returned in the list of videos. 為確保視頻是清單中的第一個視頻,請將請求的ID查詢參數設置為此 ID。To ensure the video is the first video in the list, set the request's id query parameter to this ID. StringString
視圖計數viewCount 在源網站觀看視頻的次數。The number of times that the video has been watched at the source site. 整數 Integer
webSearchUrlwebSearchUrl 將使用者帶到必應視頻搜尋結果並播放視頻的 URL。The URL that takes the user to the Bing video search results and plays the video. StringString
widthwidth 視頻的寬度(以圖元為單位)。The width of the video, in pixels. 整數 Integer

影片Videos

當視頻請求成功時,回應包括的頂級物件。The top-level object that the response includes when the video request succeeds.

如果服務懷疑拒絕服務攻擊,請求將成功(HTTP 狀態碼為 200 OK),但回應正文為空。If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK), but the body of the response is empty.

名稱Name Value 類型Type
_type_type 類型提示。Type hint. StringString
下一個偏移nextOffset 偏移量查詢參數設置為的偏移量值。The offset value that you set the offset query parameter to.

如果在第一offset個請求上count設置為 0 和 30,然後在第offset二個請求上設置為 30,則第二個回應中的某些結果可能是第一個回應的重複結果。If you set offset to 0 and count to 30 on your first request, and then set offset to 30 on your second request, some of the results in the second response may be duplicates of the first response.

為了防止重複,請設置為offset的值nextOffsetTo prevent duplicates, set offset to the value of nextOffset.
整數 Integer
樞軸建議pivotSuggestions 分割原始查詢的透視清單。A list of pivots that segment the original query. 例如,如果查詢是 "清理古特", 必應可能會將查詢分為 "清理"和"古特"。For example, if the query was Cleaning Gutters, Bing might segment the query into Cleaning and Gutters.

"清潔"資料透視可能包含查詢建議,如"古特安裝"和"古特"修復,而古特斯樞軸可能包含查詢建議,如屋頂清潔和視窗清潔。The Cleaning pivot may contain query suggestions such as Gutter Installation and Gutter Repair, and the Gutters pivot may contain query suggestions such as Roof Cleaning and Window Cleaning.
樞軸 Pivot[]
查詢擴展queryExpansions 縮小原始查詢範圍的展開查詢的清單。A list of expanded queries that narrows the original query. 例如,如果查詢是 "清潔+古特", 則擴展的查詢可能是:古特清潔工具從地面清潔排水溝、古特清潔地溝清潔。For example, if the query was Cleaning+Gutters, the expanded queries might be: Gutter Cleaning Tools, Cleaning Gutters From the Ground, Gutter Cleaning Machine, and Easy Gutter Cleaning. 查詢 Query[]
總估計匹配項totalEstimatedMatches 與查詢匹配的視頻的估計數量。The estimated number of videos that match the query. 使用此編號以及計數偏移查詢參數來對結果進行頁面。Use this number along with the count and offset query parameters to page the results.

僅視頻搜索 API 回應包括此欄位。Only Video Search API responses include this field.
longLong
valuevalue 與查詢相關的視頻清單。A list of videos that are relevant to the query. 視頻 Video[]
webSearchUrlwebSearchUrl 請求視頻的必應搜尋結果的 URL。The URL to the Bing search results for the requested videos. StringString

錯誤碼Error codes

以下是要求傳回的可能 HTTP 狀態碼。The following are the possible HTTP status codes that a request returns.

狀態碼Status Code 描述Description
200200 成功。Success.
400400 缺少其中一個查詢參數,或查詢參數無效。One of the query parameters is missing or not valid.
401401 缺少訂用帳戶金鑰或無效。The subscription key is missing or is not valid.
403403 使用者已通過身分驗證 (例如已使用有效的訂用帳戶金鑰),但並未擁有所要求的資源的權限。The user is authenticated (for example, they used a valid subscription key) but they don’t have permission to the requested resource.

如果呼叫者超過其每月查詢配額,Bing 可能也會傳回此狀態。Bing may also return this status if the caller exceeded their queries per month quota.
410410 要求所用的是 HTTP 而非 HTTPS 通訊協定。The request used HTTP instead of the HTTPS protocol. HTTPS 是唯一支援的通訊協定。HTTPS is the only supported protocol.
429429 呼叫者超過其每秒查詢配額。The caller exceeded their queries per second quota.
500500 未預期的伺服器錯誤。Unexpected server error.

如果要求失敗,回應會包含 ErrorResponse 物件,內有說明錯誤原因的 Error 物件清單。If the request fails, the response contains an ErrorResponse object, which contains a list of Error objects that describe what caused of error. 如果錯誤與參數有關,則 parameter 欄位會識別有問題的參數。If the error is related to a parameter, the parameter field identifies the parameter that is the issue. 如果錯誤與參數值有關,則 value 欄位會識別無效的值。And if the error is related to a parameter value, the value field identifies the value that is not valid.

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

以下是可能的錯誤碼和子錯誤碼值。The following are the possible error code and sub-error code values.

程式碼Code 子代碼SubCode 描述Description
ServerErrorServerError UnexpectedErrorUnexpectedError
ResourceErrorResourceError
NotImplementedNotImplemented
HTTP 狀態碼為 500。HTTP status code is 500.
InvalidRequestInvalidRequest ParameterMissingParameterMissing
ParameterInvalidValueParameterInvalidValue
HttpNotAllowedHttpNotAllowed
BlockedBlocked
只要要求的任何部分無效,Bing 就會傳回 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.

如果您使用的是 HTTP 通訊協定,而不是 HTTPS,Bing 會傳回 HttpNotAllowed,且 HTTP 狀態碼為 410。If you use the HTTP protocol instead of HTTPS, Bing returns HttpNotAllowed, and the HTTP status code is 410.
RateLimitExceededRateLimitExceeded 沒有子代碼No sub-codes 每當您超過每秒查詢 (QPS) 或每月查詢 (QPM) 配額時,Bing 會傳回 RateLimitExceeded。Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota.

如果您超過 QPS,Bing 會傳回 HTTP 狀態碼 429,如果您超過 QPM,Bing 會傳回 403。If you exceed QPS, Bing returns HTTP status code 429, and if you exceed QPM, Bing returns 403.
InvalidAuthorizationInvalidAuthorization AuthorizationMissingAuthorizationMissing
AuthorizationRedundancyAuthorizationRedundancy
當 Bing 無法驗證呼叫者時,Bing 會傳回 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
當呼叫者沒有資源存取權限時,Bing 會傳回 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.

市場代碼Market codes

下表列出了可用於指定mkt查詢參數的市場代碼值。The following table lists the market code values that you may use to specify the mkt query parameter. Bing 只會傳回這些市場的內容。Bing returns content for only these markets. 清單會隨時變動。The list is subject to change.

有關可在cc查詢參數中指定的國家/地區代碼的清單,請參閱國家/地區代碼For a list of country codes that you may specify in the cc query parameter, see Country codes.

國家/區域Country/Region 語言Language 市場代碼Market code
阿根廷Argentina 西班牙文Spanish es-ARes-AR
澳大利亞Australia 英文English en-AUen-AU
奧地利Austria 德文German de-ATde-AT
比利時Belgium 荷蘭文Dutch nl-BEnl-BE
比利時Belgium 法文French fr-BEfr-BE
巴西Brazil 葡萄牙文Portuguese pt-BRpt-BR
CanadaCanada 英文English en-CAen-CA
CanadaCanada 法文French fr-CAfr-CA
智利Chile 西班牙文Spanish es-CLes-CL
丹麥Denmark 丹麥文Danish da-DKda-DK
芬蘭Finland 芬蘭文Finnish fi-FIfi-FI
法國France 法文French fr-FRfr-FR
德國Germany 德文German de-DEde-DE
香港特別行政區Hong Kong SAR 繁體中文Traditional Chinese zh-HKzh-HK
印度India 英文English en-INen-IN
印尼Indonesia 英文English en-IDen-ID
義大利Italy 義大利文Italian it-ITit-IT
日本Japan 日文Japanese ja-JPja-JP
南韓Korea 韓文Korean ko-KRko-KR
馬來西亞Malaysia 英文English en-MYen-MY
墨西哥Mexico 西班牙文Spanish es-MXes-MX
荷蘭Netherlands 荷蘭文Dutch nl-NLnl-NL
紐西蘭New Zealand 英文English en-NZen-NZ
中華人民共和國People's republic of China 中文Chinese zh-CNzh-CN
波蘭Poland 波蘭文Polish pl-PLpl-PL
葡萄牙Portugal 葡萄牙文Portuguese pt-PTpt-PT
菲律賓共和國Republic of the Philippines 英文English en-PHen-PH
俄羅斯Russia 俄文Russian ru-RUru-RU
沙烏地阿拉伯Saudi Arabia 阿拉伯文Arabic ar-SAar-SA
南非South Africa 英文English en-ZAen-ZA
西班牙Spain 西班牙文Spanish es-ESes-ES
瑞典Sweden 瑞典文Swedish sv-SEsv-SE
瑞士Switzerland 法文French fr-CHfr-CH
瑞士Switzerland 德文German de-CHde-CH
台灣Taiwan 繁體中文Traditional Chinese zh-TWzh-TW
土耳其Turkey 土耳其文Turkish tr-TRtr-TR
United KingdomUnited Kingdom 英文English en-GBen-GB
美國United States 英文English zh-TWen-US
美國United States 西班牙文Spanish es-USes-US

國碼Country codes

以下是在 cc 查詢參數中能夠指定的國家/地區代碼。The following are the country codes that you may specify in the cc query parameter. 清單會隨時變動。The list is subject to change.

國家/區域Country/Region 國碼 (地區碼)Country code
阿根廷Argentina ARAR
澳大利亞Australia AUAU
奧地利Austria ATAT
比利時Belgium BEBE
巴西Brazil BRBR
CanadaCanada CACA
智利Chile CLCL
丹麥Denmark DKDK
芬蘭Finland FIFI
法國France FRFR
德國Germany DEDE
香港特別行政區Hong Kong SAR HKHK
印度India ININ
印尼Indonesia IDID
義大利Italy ITIT
日本Japan JPJP
南韓Korea KRKR
馬來西亞Malaysia MYMY
墨西哥Mexico MXMX
荷蘭Netherlands NLNL
紐西蘭New Zealand NZNZ
挪威Norway NO
中華人民共和國People's Republic of China CNCN
波蘭Poland PLPL
葡萄牙Portugal PTPT
菲律賓共和國Republic of the Philippines PHPH
俄羅斯Russia RURU
沙烏地阿拉伯Saudi Arabia SASA
南非South Africa ZAZA
西班牙Spain ESES
瑞典Sweden SESE
瑞士Switzerland CHCH
台灣Taiwan TWTW
土耳其Turkey TRTR
United KingdomUnited Kingdom GBGB
美國United States USUS

必應支援的語言Bing supported languages

以下是可在setLang查詢參數中指定的必應支援的語言。The following are the Bing supported languages that you may specify in the setLang query parameter. 清單會隨時變動。The list is subject to change.

支援的語言Supported Languages 語言代碼Language Code
阿拉伯文Arabic arar
巴斯克文Basque 歐盟eu
孟加拉文Bengali bnbn
保加利亞文Bulgarian bgbg
卡達隆尼亞文Catalan ca
中文 (簡體)Chinese (Simplified) zh-hanszh-hans
中文 (繁體)Chinese (Traditional) zh-hantzh-hant
克羅埃西亞文Croatian hrhr
捷克文Czech cscs
丹麥文Danish dada
荷蘭文Dutch nlnl
英文English enen
英語-英國English-United Kingdom en-gben-gb
愛沙尼亞文Estonian etet
芬蘭文Finnish fifi
法文French frfr
加利西亞文Galician glgl
德文German dede
古吉拉特文Gujarati gugu
HebrewHebrew hehe
HindiHindi hihi
匈牙利文Hungarian huhu
冰島文Icelandic isis
義大利文Italian itit
日文Japanese Jpjp
坎那達文Kannada knkn
韓文Korean koko
拉脫維亞文Latvian lvlv
立陶宛文Lithuanian ltlt
馬來文Malay msms
馬來亞拉姆文Malayalam  mlml
馬拉地文Marathi mrmr
挪威文 (巴克摩)Norwegian (Bokmål) nbnb
波蘭文Polish plpl
葡萄牙文 (巴西)Portuguese (Brazil) pt-brpt-br
葡萄牙文 (葡萄牙)Portuguese (Portugal) pt-ptpt-pt
旁遮普文Punjabi papa
羅馬尼亞文Romanian roro
俄文Russian ruru
塞爾維亞文(青色)Serbian (Cyrylic) sr
斯洛伐克文Slovak sksk
斯洛維尼亞文Slovenian slsl
西班牙文Spanish eses
瑞典文Swedish svsv
坦米爾文Tamil tata
泰盧固文Telugu tete
泰文Thai thth
土耳其文Turkish trtr
烏克蘭文Ukrainian ukuk
越南文Vietnamese vi