端點：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 | 字串 | 「嚴格」 | 安全搜尋篩選的層級。 價值觀：「關」、「嚴格」。 預設是「嚴格」。 |
內容格式
設定 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 陣列 | 網頁結果列表。 |
| 查詢訊號 | 查詢訊號 | 查詢層級排名是搜尋查詢的訊號。 |
| 風險等級 | 字串 | 查詢時會評估安全風險等級。 可能的值： 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 時仍會顯示。 |
| contentTier | 字串 | 結果的內容層級，描述內容來源的商業存取特性。 可能的價值： standard （標準內容在預設服務提供下，所有客戶皆可使用）、 entitled （透過現有客戶授權協議，包括客戶直接從出版商授權並透過自身合約取得存取的自 帶授權（BYOL） 內容）、 premium （提供超出標準服務且需計費的優質內容）。 |
Note
和欄位的值crawledAtlastUpdatedAt為可選。 也就是說，他們的保障範圍不是100%。 你可能會看到這些欄位的值為空。
錯誤代碼
| 狀態代碼 | 錯誤類別 | Description | 常見的原因 |
|---|---|---|---|
| 200 | Success | 請求成功。 | - |
| 400 | 錯誤的請求 | 請求參數無效。 | 缺少必填欄位、參數值無效、JSON 格式錯誤 |
| 401 | Unauthorized | 驗證失敗或缺失。 | API 金鑰無效，缺少 x-apikey 標頭 |
| 403 | 禁止 | 有效的憑證，但權限不足。 | API 金鑰缺乏所需權限 |
| 410 | 消失了 | 需要 HTTPS 認證。 | 請求是透過 HTTP 而非 HTTPS 進行的 |
| 415 | 不支援媒體類型 | 內容類型不支援。 | 缺少或錯誤的內容類型標頭 |
| 429 | 過多要求 | 速率超過上限。 | 時間窗口內請求太多 |
| 500 | 內部伺服器錯誤 | 未預期的伺服器錯誤。 | 臨時伺服器問題 |
| 503 | 服務不可用 | 服務暫時無法使用。 | 維護或暫時停電 |
| 504 | 閘道逾時 | 要求已逾時。 | 上游服務逾時 |
如需詳細的錯誤處理指引，請參見 錯誤處理。