端點: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"
}'
範圍請求範例
要依來源篩選新聞結果,請依「 用範圍篩選結果」中描述的命名範圍建立並驗證。 以下請求使用選定 Web IQ AppID 帳單帳戶中命名 ProductDocs 的範圍:
curl -X POST "https://api.microsoft.ai/v3/search/news" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "product announcements",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000
}'
請依照範圍的納入與排除規則審查網址 newsResults 。 該範圍篩選可用的新聞內容;它不保證收錄網站的新聞文章一定是匹配的索引。 零匹配結果不代表範圍與應用失敗。 請設定 failOnMissingScope 為 true 未範圍結果不可接受的時間。 請參閱 「解讀結果 」以了解反應解釋及傳播預防措施。
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“。 |
| freshness | No | 字串 | - | 根據發現日期篩選結果的時間範圍。 支援「day」、「week」、「month」、「year」來表示相對時間,或是 ISO 8601 日期間隔格式:「YYYY-MM-DD/YYYY-MM-DD」或「YYYY-MM-DDTHH:mm:ssZ/YYYY-MM-DDTHH:mm:ssZ」,以表示日期/日期時間範圍,請使用 .. 省略開始或結束日期。 在範圍開始前12小時或結束後發現的結果可回傳;這是預期之內的。 |
| contentFormat | No | 字串 | 「段落」(「文本」,具備完整文件存取權) |
passage 回傳每個結果中與查詢最相關的部分(建議用於接地)。
text
html,並markdown返回完整文件,僅適用於擁有完整文件存取權的應用程式;詳見段落與內容格式。 每個請求都設定它。 |
| 最大長度 | No | 整數 | 3000(10000 可完整存取文件) | 每個結果的最大 content 字元數為 1 到 500000。 沒有完整文件存取權, content 最多只有 3000 個字元。 請參閱 預設值與限制。 每個請求都設定它。 |
| 範圍名稱 | 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 該結果何時被報告。 有效作用域可對任一值套用;零匹配結果並非示范範圍失效。 沒有命名的範圍就沒有效果。 請參閱 命名範圍錯誤。 |
Note
freshness 設為「日」會降低相關性。 只有在需要最後一天的成果時才用。
內容格式
設定 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 |
|---|---|---|
| 新聞結果 | 新聞結果 | 新聞報導結果列表。 |
| 適用範圍 | 布林值(可選) |
true 表示所請求的範圍已被應用,而不一定是最新的定義。
false 表示未適用範圍; failOnMissingScope: false 允許這種無範圍的回應。 當服務未報告申請結果時,則會省略。 沒有 scopeName,則不請求命名範圍;不要假設欄位存在或總是 false。 描述的是目前的請求,而非全域傳播。 |
| 儀器 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 |