Note
Auto 和 Auto Advanced 功能自 2026 年 11 月 17 日起一般可於所有 Web IQ AppID 上使用。 沒有完整文件存取權的 AppID 會拿到段落。
端點:POST https://api.microsoft.ai/v3/auto
所有請求都需要 API 金鑰或 Microsoft Entra ID 存取權杖。 請參閱 認證 部分的設定說明。
範例要求
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "Microsoft AI announcements",
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321",
"mode": "lite",
"maxResponseLength": 30000,
"maxCitations": 10,
"responseFilter": ["web", "news"]
}'
範圍請求範例
若要在自動中使用命名範圍篩選網頁與新聞檢索(參見 「含範圍篩選結果」),請包含 scopeName 和 failOnMissingScope:
curl -X POST "https://api.microsoft.ai/v3/auto" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "product setup guide",
"scopeName": "ProductDocs",
"failOnMissingScope": true,
"mode": "lite",
"responseFilter": ["web", "news"]
}'
Parameters
| 參數 | Required | 類型 | Default | Description |
|---|---|---|---|---|
query |
Yes | 字串 | - | 搜尋查詢,字元範圍從 1 到 1,000 字元。 |
language |
No | 字串 | en |
兩字母 ISO 639-1 介面語言。 |
region |
No | 字串 | US |
兩個字母的市場或國家/地區代碼。 |
mode |
No | 字串 | lite |
lite 優先考量速度; advanced 重視全面性。 |
maxResponseLength |
No | 整數 | 30000 | 網頁結果的最大內容長度,而非總回應長度。 低於1500的數值則被限制在1500;超過 500000 的數值則被夾在 500000。 對於沒有完整文件存取權的 AppID,最高可達 30000。 |
maxCitations |
No | 整數 | 10 | 最多可申請的網路引用數,從 1 到 50。 小於1的數值會被夾到1;超過50的數值上限為50。 |
location |
No | 字串 | - | 例如lat:47.6062;long:-122.3321格式中的地理背景lat:<latitude>;long:<longitude>。 |
responseFilter |
No | 字串陣列 | - | 符合資格的答案類型:web, news, timezone, imagesweathervideos。 |
includeSites |
No | 字串陣列 | - | 限制符合資格的網路結果僅限於這些網站(具有可選路徑的網域),最多可有 250 筆條目。 新聞和其他答案類型不會被過濾。 保持清單簡短且相關,以達到最佳效果。 步道最多可支撐兩段;較深的路徑會被截斷,因此 example.com/a/b/c 被視為 example.com/a/b。 |
excludeSites |
No | 字串陣列 | - | 省略這些網站(含可選路徑的網域)的網路結果,最多有 250 個條目,且路徑規則 includeSites與 相同。 如果網站同時出現在兩個清單中,則會被排除在外。 新聞和其他答案類型不會被過濾。 |
scopeName |
No | 字串 | - | 從指定的集合中,分配給所選 Web IQ AppID 帳單帳號的一個命名範圍。 使用 1-128 個 ASCII 字母、數字、.、_-,且不留空格。 對於自動,瞄準鏡只限制網路和新聞結果。 其他答案類型未被範圍過濾,且可能包含範圍外的結果,即使 scopeApplied 是 true。 省略或 null 表示未要求指定範圍。 請參閱 用Scopes篩選結果。 |
failOnMissingScope |
No | boolean | true |
控制項備用; scopeName省略或 null 表示 true。 若服務回報無法套用範圍, true 則回傳 HTTP 400 (HandlerInvalidInput) 以表示確認缺失的範圍,或返回 HTTP 500 (ScopeFailedToApply) 以回應其他範圍失敗。
false 允許在不使用範圍的情況下搜尋,並以 scopeApplied: false 該結果何時被報告。 有效作用域可對任一值套用;零匹配結果並非示范範圍失效。 沒有命名的範圍就沒有效果。 請參閱 命名範圍錯誤。 |
回應
成功的證據回應會返回 200 OK。 每個結果包含一個打型的證據物件及其支持的引用。 未被支持或錯誤的證據及其引用資料均被省略。 若所有提供的證據結果都被省略,則 results 為空。
自我證據回應
| Field | 類型 | Description |
|---|---|---|
results |
自動證據結果陣列 | 證據項目與引用的範圍都指向該結果。 |
querySignals |
查詢訊號 | 查詢層級排名是搜尋查詢的訊號。 |
scopeApplied |
布林值(可選) |
true 表示所請求的範圍已被應用,而不一定是最新的定義。
false 表示未適用範圍; failOnMissingScope: false 允許這種無範圍的回應。 當服務未報告申請結果時,則會省略。 沒有 scopeName,則不請求命名範圍;不要假設欄位存在或總是 false。 描述的是目前的請求,而非全域傳播。 |
traceId |
字串 | 用於除錯與支援的關聯性 ID。 |
查詢訊號
| Field | 類型 | Description |
|---|---|---|
freshness |
boolean | 指出此查詢是否應優先處理新文件。 |
自動證據結果
| Field | 類型 | Description |
|---|---|---|
evidence |
自證 | 產生了打字證據。 |
citations |
自動證據引證陣列 | 僅有支持此證據的引用。 |
自證
證據物件自身 type 的判別子選擇 的 content範式。 使用 證據類型索引 來找出相應的定義。
| Field | 類型 | Description |
|---|---|---|
type |
字串 | 鑑別器識別證據架構。 數值是區分大小寫的,例如 structured/timeZone。 |
content |
字串或物件 | 文字或結構化內容,其形狀依賴於 type。 |
自動證據引用
引用欄位會依答案類型及可用來源元資料而異。 並非每個領域都出現在每條引用中。
| Field | 類型 | Description |
|---|---|---|
contentSource |
字串 | 引用來源。 |
source |
字串 | 該地點名稱。 |
siteIcon |
字串 | 引用網站的圖示網址。 |
title |
字串 | 引用標題。 |
url |
字串 | 引用網址。 |
publishedBy |
字串 | 引用內容的Publisher。 |
hostPageUrl |
字串 | 載有該引用內容的頁面網址。 |
lastUpdatedAt |
字串 | 最後更新時間戳。 |
crawledAt |
字串 | 爬取時間戳記。 |
language |
字串 | 內容語言。 |
isAdult |
boolean | 引用是否包含成人內容。 當 true;將遺漏欄位 false視為 時,明確返回 。 |
針對特定答案的引用也可以包含以下中繼資料:
| Field | 類型 | 適用對象 | Description |
|---|---|---|---|
observedAt |
字串 | Weather | 觀察時間戳由引用來源提供。 |
範例回應
{
"results": [
{
"evidence": {
"type": "text",
"content": "Microsoft announced a new set of AI capabilities."
},
"citations": [
{
"contentSource": "web",
"url": "https://www.microsoft.com/en-us/ai",
"title": "Microsoft AI",
"language": "en"
}
]
}
],
"querySignals": { "freshness": true },
"traceId": "00000000000000000000000000000000"
}
在此範例中, isAdult 省略了 ,因此客戶端應將其視為 false。
證據類型
利用這個索引查找證據物件的 content 結構圖。 請求 responseFilter 中的答案類別與回應中的證據區分器不同:例如, timezone 請求是時區答案,而回傳的證據類型是 structured/timeZone。
| 答案類別 | 證據 type |
內容定義 |
|---|---|---|
web |
text |
文字證據:字串內容。 |
news |
text/news |
文字證據:串內容,並附有可選的縮圖。 |
images |
media/image |
圖片證據:圖片尺寸、說明與縮圖。 |
videos |
media/video |
影片證據:播放元資料、縮圖和可選片段。 |
weather |
structured/weather |
天氣物件:狀況、預報、警報及日照資料。 |
timezone |
structured/timeZone |
時區物件:當地時間、UTC 偏移量與比較。 |
以下定義描述公共領域。 欄位不可用時可省略;省略的場並不代表測量值為零或答案為空。 來源元資料與歸屬屬於所附結果的 引用,而非每個定義中重複的回應信封。
範例是說明 evidence 性的片段,而非完整的回應。 請參考 範例回應 以了解包圍 results 與 citations 結構。
文本證據
對於 text (Web)和 text/news (News), content 是字串而非物件。 新聞證據也可能包含 thumbnail 一個與 content。
| Field | 類型 | Description |
|---|---|---|
content |
字串 | 結果的簡訊證據。 |
thumbnail |
物件(可選) | 新聞縮圖,包含 url (string)、 width (整數)和 height (整數)。 尺寸以像素為單位。 |
{
"type": "text/news",
"content": "An example news summary.",
"thumbnail": {
"url": "https://example.com/news-thumbnail.jpg",
"width": 320,
"height": 180
}
}
影像證據
對於 media/image, content 是一個影像物件。 來源圖片網址、主機頁面網址、標題及來源日期會在結果引用中提供(如有)。
| 內容欄位 | 類型 | Description |
|---|---|---|
caption |
字串 | 生成圖片描述。 |
width |
整數 | 影像寬度(以像素為單位)。 |
height |
整數 | 圖像高度(以像素為單位)。 |
thumbnailUrl |
字串 | 縮圖影像 URL。 |
lastUpdatedAt |
字串 | 來源日期為 ISO 8601 格式(如有)。 |
{
"type": "media/image",
"content": {
"caption": "An example city skyline.",
"width": 1920,
"height": 1080,
"thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
}
}
影片證據
對於 media/video, content 是一個視訊物件。 如影片標題、網址、發布者及來源日期等來源細節,會在結果引用中提供(如有)。
| 內容欄位 | 類型 | Description |
|---|---|---|
description |
字串 | 影片內容說明。 |
summary |
字串 | 影片的簡短摘要或重點。 |
viewCount |
整數 | 影片觀看次數。 |
length |
字串 | 影片長度格式。HH:MM:SS |
allowHttpsEmbedding |
boolean | 是否允許 HTTPS 嵌入。 |
allowMobileEmbedding |
boolean | 行動嵌入是否被允許。 |
embeddingUrl |
字串 | 嵌入影片的網址。 |
thumbnailUrl |
字串 | 影片縮圖網址。 |
width |
整數 | 影片寬度以像素為單位。 |
height |
整數 | 影片高度(像素)。 |
lastUpdatedAt |
字串 | 來源日期為 ISO 8601 格式(如有)。 |
bestMomentIndex |
整數 | 最佳時刻或亮點的索引(如有)。 |
moments |
VideoMoment 陣列 | 有影片片段(如有)。 陣列可以是空的。 |
{
"type": "media/video",
"content": {
"viewCount": 1200,
"length": "00:02:30",
"thumbnailUrl": "https://example.com/video-thumbnail.jpg",
"moments": []
}
}
影片時刻
| Field | 類型 | Description |
|---|---|---|
title |
字串 | 單元標題。 |
description |
字串 | 該單元說明。 |
startTime |
字串 | 段落開始時間的格式。d.hh:mm:ss |
endTime |
字串 | 段落結束時間。d.hh:mm:ss |
momentUrl |
字串 | 直接連結到該單元。 |
天氣天體
當查詢是關於天氣時,Auto 可以為每個地點回傳一個 structured/weather 結果。 欄位在有時會附上。 閱讀數值 units測量與;不要假設固定單位制。
| 內容欄位 | 類型 | Description |
|---|---|---|
location |
字串 | 例如 Seattle, Washington地點名稱。 |
url |
字串 | 地點的天氣歸因網址。 結果引用中也有相同的網址。 |
units |
物件 | 單位系統(system)以及 的temperature單位 、 speed、 heightpressuredistancetime和 。 |
alerts |
WeatherAlert 陣列 | 根據用戶所在國家或地區篩選該地點的活躍或近期天氣警報。 |
currentWeather |
物件 | 目前狀況,包括 condition、 dayPeriod、 temperature、 airQualityuvLevelwindSpeeduvwindDirectionwindGustfeelsLikehumidityobservedAtuniversalThermalClimateIndexdewPointpressurevisibility及 (若有時)。 |
forecastedWeather |
物件陣列 | 每日預報,包含 validDate、 condition、 feelsLikeLowtemperatureLowtemperatureHighprecipitationChancefeelsLikeHigh降雨量、 humidity、 daynightalmanachourly ,以及在有資料時的預報。 |
sunlight |
物件 | 當查詢要求特定日期時,日出、日落、月出、月落和月相。 |
電流 airQuality 可以包含 index、 severity、 primaryPollutant和 validAt。 每日預報 humidity 可以包含 high 和 low。 其 day 及 night 子預測可以包含 condition、 precipitationChance、 windSpeed和 windDirection。 它almanac包含了太陽和月亮的資料。validDate
{
"type": "structured/weather",
"content": {
"location": "Seattle, Washington",
"units": {
"system": "Imperial",
"temperature": "F"
},
"currentWeather": {
"condition": "Cloudy",
"temperature": 50
}
}
}
天氣警報
| Field | 類型 | Description |
|---|---|---|
id |
字串 | 提供提供者提供的警示識別碼(如有)。 |
name |
字串 | 例如 Frost天氣事件名稱。 |
severity |
字串 | 嚴重度,例如 Advisory, Watch,或 Warning。 |
status |
字串 | 例如 Ongoing警報狀態。 |
issuingAuthority |
字串 | 例如,發布警報 National Weather Service的組織。 |
url |
字串 | 連結至發行機構。 當來源提供時,會包含在內。 |
description |
字串 | 危險描述及受影響區域。 |
safetyGuidance |
字串 | 建議的安全措施(如有)。 |
issuedAt、effectiveAt、expiresAt |
字串 | 警報何時發出、生效並失效。 |
時區物件
對於 structured/timeZone, content 描述當地時間或比較兩個時區。 位置查詢可以回傳 timeZones;比較則可以回傳 startTimeZone、 endTimeZone、 timeDifference。 不必要求每個答案都包含這些欄位。
| 內容欄位 | 類型 | Description |
|---|---|---|
description |
字串 | 如有,提供可讀的答案摘要。 |
timeZones |
時區輸入陣列 | 單一地點或多地點時間答案的條目。 |
startTimeZone |
時區輸入 | 資料來源時區,供比較。 |
endTimeZone |
時區輸入 | 目標時區作比較。 |
timeDifference |
字串 | 用於比較的人類可讀時差描述。 |
{
"type": "structured/timeZone",
"content": {
"timeZones": [
{
"timeZoneName": "Pacific Standard Time",
"timeZoneAbbreviation": "PST",
"location": "Seattle, Washington",
"utcOffset": -8,
"utcTime": "Monday, 2026-11-16T05:00:00Z",
"localTime": "Sunday, 2026-11-15T21:00:00-08:00"
}
]
}
}
時區輸入
| Field | 類型 | Description |
|---|---|---|
timeZoneName |
字串 | 完整的時區名稱。 |
timeZoneAbbreviation |
字串 | 縮寫,例如PSTIST或 。 |
location |
字串 | 與參賽作品相關的城市、國家或地區。 |
utcOffset |
number | UTC相沖時間在幾小時後。 例如,可以是分數式 5.5,或在無法使用時省略。 |
utcTime |
字串 | UTC 時間以格式化字串表示。 |
localTime |
字串 | 當地時間以格式化字串表示。 |
時間串可以包含星期幾前綴;不要以為它們是裸露的 ISO 8601 時間戳記。
錯誤碼
| 狀態代碼 | Description |
|---|---|
| 200 | 申請成功,包括有效的搜尋但未找到結果。 |
| 400 | 參數無效或 JSON 格式錯誤。 |
| 401 | 缺少或無效的認證憑證。 |
| 403 | 經過認證的 Web IQ AppID 並未啟用自動。 |
| 429 | 超出資歷或配額上限。 |
| 500 | 內部服務失敗。 |
| 503 | 必須的服務無法提供。 |
| 504 | 要求已逾時。 |
關於共享錯誤結構與重試指引,請參見 錯誤處理。