網頁搜尋 REST API 參考

終點:POST https://api.microsoft.ai/v3/search/web

範例請求:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

參數 Required 類型 Default Description
查詢 Yes 字串 - 一個搜尋查詢字串。 長度上限為 1000 個字元。 支援「site:」和「-site:」運算子,以包含或排除特定網站的結果(例如「query site:example.com」)。 僅在必要時使用這些運算子,因為它們本質上會降低結果的相關性。
maxResults No 整數 10 要傳回的結果數目上限。 預設值是10,最高值是50。
語言 No 字串 「en」 搜尋結果中介面語言的兩字母 ISO 639-1 語言代碼。 完整列表請參閱 支援語言 。
區域 No 字串 "US" 一個兩字母的國家/地區代碼,表示結果應該來自哪裡(例如「US」、「JP」、「GB」等)。 完整列表請參閱 支援區域 。
位置 No 字串 - 位置資訊格式為「緯度:<浮點>;long:<float>」,例如「緯度:40.753250;長度:-74.003807“。 若未指定,則會推斷查詢中的位置。
contentFormat No 字串 「段落」(「HTML」,具備完整文件存取權) passage 回傳每個結果中與查詢最相關的部分(建議用於接地)。 text html,並markdown返回完整文件,僅適用於擁有完整文件存取權的應用程式;詳見段落與內容格式。 每個請求都設定它。 注意:網頁 API 不會回傳欄位 snippet 。
最大長度 No 整數 3000(10000 可完整存取文件) 每個結果的最大 content 字元數為 1 到 500000。 沒有完整文件存取權, content 最多只有 3000 個字元。 請參閱 預設值與限制。 每個請求都設定它。
safeSearch No 字串 「嚴格」 安全搜尋篩選的層級。 價值觀:「關」、「嚴格」。 預設是「嚴格」。
範圍名稱 No 字串 - 從指定的集合中,分配給所選 Web IQ AppID 帳單帳號的一個命名範圍。 使用 1-128 個 ASCII 字母、數字、.、_-,且不留空格。 省略或 null 表示未要求指定範圍。 請參閱 用Scopes篩選結果。
失敗在缺失的範圍 No boolean true 控制項備用; scopeName省略或 null 表示 true。 若服務回報無法套用範圍, true 則回傳 HTTP 400 (HandlerInvalidInput) 以表示確認缺失的範圍,或返回 HTTP 500 (ScopeFailedToApply) 以回應其他範圍失敗。 false 允許在不使用範圍的情況下搜尋,並以 scopeApplied: false 該結果何時被報告。 有效作用域可對任一值套用;零匹配結果並非示范範圍失效。 沒有命名的範圍就沒有效果。 請參閱 命名範圍錯誤。

內容格式

設定 contentFormat = passage 為取得每個結果中與查詢最相關的部分,最多可達 maxLength 字元(3000 字元是個不錯的起點)。 這是建議的接地形式;請參閱常見問題集,請參考 What is passage, and why use it? 。 具備完整文件存取權的應用程式也可以請求完整文件,格式為 ,html或markdown;text對於其他應用程式,這些格式會回傳 HTTP 403。 請參閱 文章與內容格式。

安全搜尋

安全搜尋模式讓你能控制 Web API 在結果回傳前過濾多少敏感的網頁內容。 敏感內容包括暴力、自我傷害及其他類別。 預設值為 strict。

Value Description 推薦閱讀
strict 封鎖與成人、大膽、暴力、仇恨及自殘主題相關的內容。 兒童安全、教育、消費者/保守派部署。
off 它仍然會封鎖非法內容。 對於其他可能有害的內容,則將最終過濾的責任轉嫁給使用者。 研究、分析、選擇加入企業、進階 3P 使用案例。

Note

如果你使用查詢運算子 site: ,回應可能包含成人內容,無論其值如何 safeSearch 。 只有在你知道網站上的內容,且你的情況支持成人內容可能性時才使用 site: 。

要求標頭

Field 類型 Description
主持人 字串 Microsoft AI API 主機: api.microsoft.ai
x-apikey 或 授權 字串 你的 API 金鑰或 Entra ID 存取權杖用於認證。
內容類型 字串 請求實體的 MIME 類型。 請使用 application/json。

回應

網路回應

Field 類型 Description
網路結果 webResult 陣列 網頁結果列表。
查詢訊號 查詢訊號 查詢層級排名是搜尋查詢的訊號。
適用範圍 布林值(可選) true 表示所請求的範圍已被應用,而不一定是最新的定義。 false 表示未適用範圍; failOnMissingScope: false 允許這種無範圍的回應。 當服務未報告申請結果時,則會省略。 沒有 scopeName,則不請求命名範圍;不要假設欄位存在或總是 false。 描述的是目前的請求,而非全域傳播。
風險等級 字串 查詢時會評估安全風險等級。 可能的值: low, moderate, high, veryHigh。
儀器 ClickBase 字串 點擊ping請求的基礎網址。 從 instrumentationSuffix 結果項目附加一個值,形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 注意:使用者點擊也可透過網址重定向來記錄。 啟用重定向時,無需操作記錄使用者點擊,且 instrumentationClickBase 回應中不會包含。 請參閱 儀器安裝指南 以了解設定說明。
儀器引用基礎 字串 LLM 日誌 ping 請求的基礎網址。 附加一個 DATA payload 以形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。
traceId 字串 用於除錯的追蹤識別碼。

查詢訊號

Field 類型 Description
freshness boolean 指出此查詢是否應優先處理新文件。

web結果

Field 類型 Description
title 字串 網頁的標題。
url 字串 網頁的原始網址。 對於啟用 URL 重定向的中國用戶,此欄位會包含與 clickUrl相同的重定向 URL。
網域 字串 結果的目的地主機。 僅針對啟用 URL 重定向的中國用戶退回。
內容 字串 網頁的詳細內容(也就是所謂的「接地」)。
crawledat 字串 網頁最後爬取日期依ISO8601格式呈現。
最後更新時間 字串 網頁最後更新日期依照ISO8601格式。
語言 字串 網頁語言採用 ISO 639-1 語言代碼。
是成人 boolean 顯示結果是否包含成人內容。
點擊網址 字串 透過 Bing 將點擊的代理網址重新導轉。 只有在啟用點擊重定向時才會出現。
配器後綴 字串 附加於此結果項目的儀器 ping URL 基底後綴。 用作儀器 ping URL 與重定向的 clickUrl K 值。 啟用儀器 ping 時仍會顯示。

Note

和欄位的值crawledAtlastUpdatedAt為可選。 也就是說,他們的保障範圍不是100%。 你可能會看到這些欄位的值為空。

錯誤代碼

狀態代碼 錯誤類別 Description 常見的原因
200 Success 請求成功。 -
400 錯誤的請求 請求參數無效。 缺少必填欄位、參數值無效、JSON 格式錯誤
401 Unauthorized 驗證失敗或缺失。 API 金鑰無效,缺少 x-apikey 標頭
403 禁止 有效的憑證,但權限不足。 API 金鑰缺乏所需權限
410 消失了 需要 HTTPS 認證。 請求是透過 HTTP 而非 HTTPS 進行的
415 不支援媒體類型 內容類型不支援。 缺少或錯誤的內容類型標頭
429 過多要求 速率超過上限。 時間窗口內請求太多
500 內部伺服器錯誤 未預期的伺服器錯誤。 臨時伺服器問題
503 服務不可用 服務暫時無法使用。 維護或暫時停電
504 閘道逾時 要求已逾時。 上游服務逾時

如需詳細的錯誤處理指引,請參見 錯誤處理。


另見:影片 搜尋 | | 瀏覽新聞 搜尋 | 圖片 搜尋 MCP |