WebSearchOptionalParams interface

要用於使用者介面字串之一或多個語言的逗號分隔清單。 清單採用喜好設定的遞減順序。 如需其他資訊，包括預期的格式，請參閱 RFC2616。 這個標頭和 setLang 查詢參數互斥;請勿同時指定兩者。 若您設定此標頭，則您也必須指定 cc 查詢參數。 Bing 會使用它從清單中找到的第一個支持語言，並將該語言與cc參數值結合，以判斷要傳回結果的市場。 如果清單不包含支持的語言，Bing 會尋找支援要求的最接近語言和市場，而且可能會針對結果使用匯總或默認市場，而不是指定的語言。 只有當您指定多種語言時，才應該使用此標頭和cc查詢參數;否則，您應該使用 mkt 和 setLang 查詢參數。 使用者介面字串是在使用者介面中作為標籤的字串。 JSON 回應物件中很少有使用者介面字串。 回應物件中 Bing.com 屬性的任何鏈接都會套用指定的語言。

acceptLanguage?: string

屬性值

您要包含回應的答案數目。 Bing 傳回的答案是以排名為基礎。 例如，如果 Bing 針對要求傳回網頁、影像、影片和 relatedSearch，而且您將此參數設定為兩個 (2) ，回應會包含網頁和影像。如果您在相同的要求中包含 responseFilter 查詢參數，並將其設定為網頁和新聞，則回應只會包含網頁。

answerCount?: number

屬性值

Bing 使用此標頭在 Bing API 所有呼叫之間為使用者提供一致的行為。 Bing 經常推出新功能和改善項目，且會以用戶端識別碼作為不同測試版指派流量的金鑰。 如果在多個要求中，未讓使用者使用相同的用戶端識別碼，Bing 可能會將使用者指派至多個衝突的測試版。 若指派給多個衝突的測試版，可能會導致使用者體驗不一致。 例如若第二個要求與第一個要求指派的測試版不同，可能會產生意料外的體驗。 此外，Bing 可以使用用戶端識別碼將 Web 結果調整為該用戶端識別碼的搜尋記錄，為使用者提供更豐富的體驗。 Bing 也會使用此標頭分析用戶端識別碼產生的活動，協助改善結果的順位。 相關性改進功能有助於 Bing API 提供更高品質的結果，進而為 API 取用者提供更高的點擊率。 重要事項：雖然是選擇性的，但您仍應將此標頭視為必要項目。 為相同的使用者和裝置組合跨多個要求保存用戶端識別碼，可讓 1) API 取用者獲得一致的使用者體驗，以及 2) 透過 Bing API 更理想的結果品質獲得較高的點擊率。 在裝置上使用您應用程式的每個使用者必須具有 Bing 產生的唯一用戶端識別碼。 如果您未在要求中包含此標頭，Bing 會產生一個識別碼，並於 X-MSEdge-ClientID 回應標頭傳回該識別碼。 不應在要求中包含此標頭的唯一時機是使用者初次在該裝置上使用您的應用程式時。 您的應用程式每次為該裝置上的該名使用者提出 Bing API 請求時，均需使用此用戶端識別碼。 保存用戶端識別碼。 若要在瀏覽器應用程式中保存識別碼，請使用永續性的 HTTP Cookie，以確保在所有工作階段均使用該識別碼。 請勿使用工作階段 Cookie。 若為其他應用程式 (例如行動裝置應用程式)，請使用裝置本身的永久儲存裝置保存識別碼。 使用者下次在該裝置上使用您的應用程式時，會取得您保存的用戶端識別碼。 Bing 回應不一定會包含此標頭。 如果回應包含此標頭，請擷取用戶端識別碼，並將其用於該裝置上使用者的所有後續 Bing 要求。 如果您包含 X-MSEdge-ClientID，則不得在要求中加入 Cookie。

clientId?: string

屬性值

用戶端裝置的 IPv4 或 IPv6 位址。 此 IP 位址可用來探索使用者的位置。 Bing 會使用位置資訊來判斷安全搜尋行為。 雖然是選擇性的，但我們仍建議您一律指定此標頭和 X-Search-Location 標頭。 請勿混淆位址 (例如，藉由將最後一個八位元變更為 0)。 混淆位址會導致位置不在裝置的實際位置附近，這可能會造成 Bing 產生錯誤結果。

clientIp?: string

屬性值

回應中傳回的搜尋結果數目。 默認值為 10，最大值為 50。 傳遞的實際數目可能小於要求。使用此參數搭配 offset 參數來頁面結果。例如，如果您的使用者介面顯示每頁 10 個搜尋結果，請將計數設定為 10，並將位移設為 0 以取得結果的第一頁。 針對每個後續頁面，遞增位移 10 (例如 0、10、20) 。 多個頁面可能會在結果中包含一些重疊。

count?: number

屬性值

產生結果的國家/地區所具備的 2 字元國碼 (地區碼)。 此 API 僅支援 美國 市場。 如果您指定此查詢參數，則必須將其設定為us。 若您設定此參數，則您也必須指定 Accept-Language 標頭。 Bing 會使用它從語言清單中找到的第一個支持語言，並將該語言與您指定要決定要傳回結果的市場代碼結合該語言。 如果語言清單不包含支持的語言，Bing 會尋找支援要求的最接近語言和市場，或者可能會針對結果使用匯總或預設市場，而不是指定的語言。 只有當您指定多種語言時，才應該使用此查詢參數和 Accept-Language 查詢參數;否則，您應該使用 mkt 和 setLang 查詢參數。 此參數和 mkt 查詢參數彼此互斥—請勿同時指定。

countryCode?: string

屬性值

依下列年齡值篩選搜尋結果：Day — 傳回 Bing 在過去 24 小時內探索到的網頁。 Week — 傳回 Bing 在過去 7 天內探索到的網頁。 Month — 傳回過去 30 天內探索的網頁。 此篩選僅適用於網頁結果，不適用於其他結果，例如新聞和影像。 可能的值包括：'Day'、'Week'、'Month'

freshness?: Freshness

屬性值

以分號分隔的索引鍵/值組清單，用以說明用戶端的地理位置。 Bing 會使用位置資訊來判斷安全的搜尋行為，以及傳回相關的區域內容。 將索引鍵/值組指定為 ：。 以下是您用來指定使用者位置的索引鍵。 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 日起的秒數。) 前端 (選擇性) ：客戶端的相對標題或移動方向。 指定 0 到 360 度的的移動方向為，計算相對於正北的順時針偏移角度。 只有在sp機碼為非零時，才指定此索引鍵。 sp (選擇性) ：用戶端裝置正在移動的水準速度 (速度) 以公尺為單位。 alt (選擇性) ：用戶端裝置的高度，以公尺為單位。 是選擇性 () ：半徑，以公尺為單位，指定座標的垂直精確度。 只有在您指定alt鍵時，才指定此索引鍵。 雖然有很多索引鍵是選擇性的，但您提供的資訊愈詳細，位置結果就愈精確。 使用者的地理位置雖然是選擇性的，但建議您一律加以指定。 如果用戶端的 IP 位址未精確反映使用者的實體位置 (例如，如果用戶端使用 VPN)，提供位置就益發重要。 若要獲得最佳結果，您應加入此標頭和 X-MSEdge-ClientIP 標頭，但加入此標頭是最基本的要求。

location?: string

屬性值

產生結果的市場。 一般而言，mkt 是使用者提出要求的國家/地區。 不過，如果使用者不在 Bing 提供結果的國家/地區，則可能是不同的國家/地區。 市場的格式必須是 -。 例如：en-US。 字串不區分大小寫。 如果已知，建議您一律指定市場。 指定市場可協助 Bing 路由傳送要求，並傳回適當的最佳回應。 如果您指定未列在市場代碼中的市場，Bing 會根據可能會變更的內部對應，使用最適合的市場代碼。 此參數和 cc 查詢參數彼此互斥—請勿同時指定。 默認值：『en-us』。

market?: string

屬性值

以零起始的位移，表示傳回結果之前要略過的搜尋結果數目。 預設值是 0。 位移應該小於 (totalEstimatedMatches - count) 。 使用此參數搭配 count 參數來分頁結果。 例如，如果您的使用者介面顯示每個頁面 10 個搜尋結果，請將計數設定為 10，並將位移設定為 0 以取得結果的第一頁。 針對每個後續頁面，遞增位移 10 (例如 0、10、20) 。 多個頁面可以在結果中包含一些重疊。

offset?: number

屬性值

根據預設，Bing 會傳回快取的內容 (如果有的話)。 若要防止 Bing 傳回快取的內容，請將 Pragma 標頭設定為 no-cache (例如，Pragma: no-cache)。

pragma?: string

屬性值

不論其排名為何，您想要回應包含的答案逗號分隔清單。 例如，如果您將 answerCount) 設定為兩個 (2) ，Bing 會傳回前兩個排名的答案，但您也想要回應包含新聞，您也會將升階為新聞。 如果排名最高的答案是網頁、影像、影片和相關搜尋，回應會包含網頁和影像，因為新聞不是排名的答案。 但是，如果您將升級為影片，Bing 會將影片答案升階為回應，並傳回網頁、影像和影片。 您想要升級的答案不會計入 answerCount 限制。 例如，如果排名的答案是新聞、影像和影片，而您將 answerCount 設定為 1 並升階為新聞，則回應會包含新聞和影像。 或者，如果已設為順位的答案為 videos、images 及 news，則回應會包含 videos 和 news。 可能的值為計算、影像、新聞、RelatedSearches、SpellSuggestions、TimeZone、影片、網頁。 只有當您指定 answerCount 時，才使用 。

promote?: AnswerType[]

屬性值

要包含在回應中的答案逗號分隔清單。 如果您未指定此參數，回應會包含有相關數據的所有搜尋答案。 可能的篩選值包括計算、影像、新聞、RelatedSearches、SpellSuggestions、TimeZone、Videos、網頁。 雖然您可以使用此篩選來取得單一答案，但您應該改用答案特定的端點來取得更豐富的結果。 例如，若要只接收影像，請將要求傳送至其中一個影像搜尋 API 端點。 RelatedSearches 和 SpellSuggestions 答案不支持個別的端點，例如影像搜尋 API 只會 (Web 搜尋 API 會傳回這些端點) 。 若要包含因排名而排除的答案，請參閱升級查詢參數。

responseFilter?: AnswerType[]

屬性值

用來篩選成人內容的篩選條件。 關閉：傳回具有成人文字、影像或影片的網頁。 中：傳回具有成人文字的網頁，但不會傳回成人影像或影片。 嚴格：不要傳回含有成人文字、影像或影片的網頁。 預設值為「中度」。 如果要求來自 Bing 成人原則要求 safeSearch 設定為 Strict 的市場，Bing 會忽略 safeSearch 值，並使用 Strict。 如果您使用網站：查詢運算符，則不論safeSearch查詢參數設定為什麼，回應都可能包含成人內容。 使用網站：只有在您知道網站上的內容，且您的案例支援成人內容的可能性時。 可能的值包括：'Off'、'Moderate'、'Strict'

safeSearch?: SafeSearch

屬性值

用於使用者介面字串的語言。 請使用 ISO 639-1 2 字母語言代碼指定語言。 例如，英文的語言代碼是 EN。 預設值為 EN (英文)。 語言雖然是選擇性的，但您應一律加以指定。 一般而言，除非使用者想要以不同語言顯示使用者介面字串，否則您將 setLang 設定為 mkt 所指定的相同語言。 此參數和 Accept-Language 標頭互斥;請勿同時指定這兩者。 使用者介面字串是在使用者介面中作為標籤的字串。 JSON 回應物件中有幾個使用者介面字串。 同樣地，回應物件中 Bing.com 屬性的任何連結都會套用指定的語言。

setLang?: string

屬性值

布爾值，決定顯示字串是否應該包含裝飾標記，例如點擊醒目提示字元。 如果為 true，字串可能會包含標記。 預設值為 false。 若要指定是否要使用 Unicode 字元或 HTML 標記做為標記，請參閱 textFormat 查詢參數。

textDecorations?: boolean

屬性值

要用於文字裝飾的標記類型， (請參閱 textDecorations 查詢參數) 。 可能的值為Raw—使用 Unicode 字元標記需要特殊格式的內容。 Unicode 字元的範圍是 E000 到 E019。 例如，Bing 會使用 E000 和 E001 來標記查詢字詞的開頭和結尾，以進行點擊醒目提示。 HTML- 使用 HTML 標籤需要特殊格式的內容。 例如，使用 標記醒目提示顯示字串中的查詢字詞。 預設值為Raw。 針對包含 、 >和 & 等<可逸出 HTML 字元的顯示字串，如果 textFormat 設定為 HTML，Bing 會視需要逸出字元 (，例如<，將字元逸出至 <) 。 可能的值包括：'Raw'、'Html'

textFormat?: TextFormat