Auto REST API 參考

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 要求已逾時。

關於共享錯誤結構與重試指引,請參見 錯誤處理。