端點：POST https://api.microsoft.ai/v3/search/news
範例請求：
curl -X POST "https://api.microsoft.ai/v3/search/news" \
-H "host: api.microsoft.ai" \
-H "x-apikey: <Your key>" \
-H "content-type: application/json" \
-d '{
"query": "latest VC funding in tech",
"maxResults": 10,
"language": "en",
"region": "US",
"maxLength": 3000,
"contentFormat": "passage"
}'
Parameters
| 參數 | Required | 類型 | Default | Description |
|---|---|---|---|---|
| 查詢 | Yes | 字串 | - | 一個新聞結果的搜尋查詢。 長度上限為 1000 個字元。 |
| maxResults | No | 整數 | 10 | 要傳回的結果數目上限。 預設值為 10。 最高價值是20。 |
| 語言 | No | 字串 | 「en」 | 搜尋結果中介面語言的兩字母 ISO 639-1 語言代碼。 完整列表請參閱 支援語言 。 |
| 區域 | No | 字串 | "US" | 一個兩字母的國家/地區代碼，表示結果應該來自哪裡（例如「US」、「JP」、「GB」等）。 完整列表請參閱 支援區域 。 |
| 位置 | No | 字串 | - | 位置資訊格式為「緯度：<浮點>;long：<float>」，例如「緯度：40.753250;長度：-74.003807“。 |
| contentFormat | No | 字串 | 「段落」（「文本」，具備完整文件存取權） |
passage 回傳每個結果中與查詢最相關的部分（建議用於接地）。
text
html，並markdown返回完整文件，僅適用於擁有完整文件存取權的應用程式;詳見段落與內容格式。 每個請求都設定它。 |
| 最大長度 | No | 整數 | 3000（10000 可完整存取文件） | 每個結果的最大 content 字元數為 1 到 500000。 沒有完整文件存取權， content 最多只有 3000 個字元。 請參閱 預設值與限制。 每個請求都設定它。 |
內容格式
設定 contentFormat = passage 為取得每個結果中與查詢最相關的部分，最多可達 maxLength 字元（3000 字元是個不錯的起點）。 這是建議的接地形式;請參閱常見問題集，請參考 What is passage， and why use it？ 。 具備完整文件存取權的應用程式也可以請求完整文件，格式為 ，html或markdown;text對於其他應用程式，這些格式會回傳 HTTP 403。 請參閱 文章與內容格式。
要求標頭
| Field | 類型 | Description |
|---|---|---|
| 主持人 | 字串 | Microsoft AI API 主機： api.microsoft.ai |
| x-apikey 或 授權 | 字串 | 你的 API 金鑰或 Entra ID 存取權杖用於認證。 |
| 內容類型 | 字串 | 請求實體的 MIME 類型。 請使用 application/json。 |
回應
新聞回應
| Field | 類型 | Description |
|---|---|---|
| 新聞結果 | 新聞結果 | 新聞報導結果列表。 |
| 儀器 ClickBase | 字串 | 點擊ping請求的基礎網址。 從 instrumentationSuffix 結果項目附加一個值，形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 注意：使用者點擊也可透過網址重定向來記錄。 啟用重定向時，無需操作記錄使用者點擊，且 instrumentationClickBase 回應中不會包含。 請參閱 儀器安裝指南 以了解設定說明。 |
| 儀器引用基礎 | 字串 | LLM 日誌 ping 請求的基礎網址。 附加一個 DATA payload 以形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 |
| traceId | 字串 | 用於除錯的追蹤識別碼。 |
新聞結果
| Field | 類型 | Description |
|---|---|---|
| title | 字串 | 新聞標題。 |
| url | 字串 | 新聞文章的來源網址。 對於啟用 URL 重定向的中國用戶，此欄位會包含與 clickUrl相同的重定向 URL。 |
| 網域 | 字串 | 結果的目的地主機。 僅針對啟用 URL 重定向的中國用戶退回。 |
| 內容 | 字串 | 新聞結果的詳細網頁內容（也就是所謂的「斷線」）。 |
| 縮圖 | 縮圖物件 | 新聞文章的縮圖。 |
| 最後更新時間 | 字串 | 新聞最後更新日期，UTC ISO8601格式。 |
| crawledat | 字串 | 新聞最後爬取日期依照ISO8601格式。 |
| 語言 | 字串 | 新聞文章的語言採用 ISO 639-1 語言代碼。 |
| 來源 | 字串 | Publisher 名稱，例如「USA TODAY |MSN、CNN 等。 |
| 是成人 | boolean | 標示內容是否為成人。 |
| 點擊網址 | 字串 | 透過 Bing 將點擊的代理網址重新導轉。 只有在啟用點擊重定向時才會出現。 |
| 配器後綴 | 字串 | 附加於此結果項目的儀器 ping URL 基底後綴。 用作儀器 ping URL 與重定向的 clickUrl K 值。 啟用儀器 ping 時仍會顯示。 |
Note
lastUpdatedAt 欄位為可選的選項——也就是說，你可能會看到這個欄位的值為空。
縮圖
| Field | 類型 | Description |
|---|---|---|
| url | 字串 | 縮圖網址。 |
| width | 整數 | 縮圖寬度，以像素為單位。 |
| height | 整數 | 縮圖高度，以像素為單位。 |
Note
thumbnail 也是可選的回應物件——某些新聞結果可能無法使用。
錯誤代碼
| 狀態代碼 | 錯誤類別 | Description | 常見的原因 |
|---|---|---|---|
| 200 | Success | 請求成功。 | - |
| 400 | 錯誤的請求 | 請求參數無效。 | 缺少必填欄位、參數值無效、JSON 格式錯誤 |
| 401 | Unauthorized | 驗證失敗或缺失。 | API 金鑰無效，缺少 x-apikey 標頭 |
| 403 | 禁止 | 有效的憑證，但權限不足。 | API 金鑰缺乏所需權限 |
| 410 | 消失了 | 需要 HTTPS 認證。 | 請求是透過 HTTP 而非 HTTPS 進行的 |
| 415 | 不支援媒體類型 | 內容類型不支援。 | 缺少或錯誤的內容類型標頭 |
| 429 | 過多要求 | 速率超過上限。 | 時間窗口內請求太多 |
| 500 | 內部伺服器錯誤 | 未預期的伺服器錯誤。 | 臨時伺服器問題 |
| 503 | 服務不可用 | 服務暫時無法使用。 | 維護或暫時停電 |
| 504 | 閘道逾時 | 要求已逾時。 | 上游服務逾時 |
如需詳細的錯誤處理指引，請參見 錯誤處理。
參見：網路搜尋 | 影片 搜尋 | | 瀏覽圖片 搜尋 MCP |