Note
从 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"]
}'
作用域内请求示例
若要使用命名范围在自动中筛选 Web 和新闻检索(请参阅范围筛选结果),包括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 |
是 | 字符串 | - | 搜索查询,从 1 到 1,000 个字符。 |
language |
否 | 字符串 | en |
双字母 ISO 639-1 界面语言。 |
region |
否 | 字符串 | US |
双字母市场或国家/地区代码。 |
mode |
否 | 字符串 | lite |
lite 确定速度的优先级; advanced 优先于全面性。 |
maxResponseLength |
否 | 整数 | 30000 | Web 结果的最大内容长度,而不是总响应长度。 低于 1500 的值被固定到 1500;超过 500000 的值被固定到 500000。 对于没有完全文档访问权限的 AppID,最大值为 30000。 |
maxCitations |
否 | 整数 | 10 | 要请求的最大 Web 引文数,从 1 到 50。 低于 1 的值被固定为 1;高于 50 的值上限为 50。 |
location |
否 | 字符串 | - | 地理上下文 lat:<latitude>;long:<longitude> 的格式,例如 lat:47.6062;long:-122.3321。 |
responseFilter |
否 | 字符串数组 | - | 符合条件的答案类型:web、、news、timezoneweather、imagesvideos。 |
includeSites |
否 | 字符串数组 | - | 将符合条件的 Web 结果限制为这些网站(具有可选路径的域),最多包含 250 个条目。 不会筛选新闻和其他答案类型。 使列表保持简短且与最佳结果相关。 路径最多支持两个段;更深层的路径将被截断,因此 example.com/a/b/c 被视为 example.com/a/b。 |
excludeSites |
否 | 字符串数组 | - | 省略这些网站(具有可选路径的域)的 Web 结果,最多包含 250 个条目和与相同的路径规则 includeSites。 如果网站出现在这两个列表中,则会将其排除。 不会筛选新闻和其他答案类型。 |
scopeName |
否 | 字符串 | - | 分配给所选 Web IQ AppID 计费帐户的集合中的一个命名范围。 使用不带空格的 1-128 ASCII 字母、 .数字、数字 _或 -空格。 对于“自动”,范围仅限制 Web 和新闻结果。 其他答案类型不会按范围进行筛选,并且可能包含其外部的结果,即使 scopeApplied 是 true。 省略或 null 表示未请求任何命名范围。 请参阅“使用范围筛选结果”。 |
failOnMissingScope |
否 | boolean | true |
控制回退; scopeName省略或 null 表示 true。 如果服务报告无法应用范围, true 则返回 HTTP 400 (HandlerInvalidInput)确认缺失范围,或返回 HTTP 500 (ScopeFailedToApply)其他范围故障。
false 允许在没有作用域的情况下进行搜索,并 scopeApplied: false 报告该结果时。 使用任一值应用有效的范围;零匹配结果不是范围失败。 在没有命名作用域的情况下不起作用。 请参阅 命名范围错误。 |
响应
成功的证据响应返回 200 OK。 每个结果都包含一个类型化的证据对象和支持它的引文。 不受支持的或格式不正确的证据与引文一起省略。 如果省略每个提供的证据结果, results 则为空。
AutoEvidenceResponse
| 领域 | 类型 | Description |
|---|---|---|
results |
AutoEvidenceResult 数组 | 与引文配对的证据项的范围限定为该结果。 |
querySignals |
QuerySignals | 搜索查询的查询级别排名信号。 |
scopeApplied |
布尔值 (可选) |
true 表示已应用请求的范围,不一定应用其最新定义。
false 表示未应用范围; failOnMissingScope: false 允许此无作用域响应。 服务不报告应用程序结果时省略。 如果没有 scopeName,则不请求命名范围;请勿假定字段存在或始终 false存在。 描述当前请求,而不是全局传播。 |
traceId |
字符串 | 用于调试和支持的相关 ID。 |
QuerySignals
| 领域 | 类型 | Description |
|---|---|---|
freshness |
boolean | 指示是否应将新文档优先于此查询的其他文档。 |
AutoEvidenceResult
| 领域 | 类型 | Description |
|---|---|---|
evidence |
AutoEvidence | 生成的类型化证据。 |
citations |
AutoEvidenceCitation 数组 | 仅支持此证据结果的引文。 |
AutoEvidence
证据对象自己的 type 歧视性选择架构 content。 使用 证据类型索引 查找相应的定义。
| 领域 | 类型 | Description |
|---|---|---|
type |
字符串 | 识别证据架构的歧视性。 值区分大小写,例如 structured/timeZone。 |
content |
字符串或对象 | 形状所依赖 type的文本或结构化内容。 |
AutoEvidenceCitation
引文字段因答案类型和可用的源元数据而异。 并非每个引文中都存在每个字段。
| 领域 | 类型 | Description |
|---|---|---|
contentSource |
字符串 | 引文源。 |
source |
字符串 | 引用的网站的名称。 |
siteIcon |
字符串 | 引用网站的图标 URL。 |
title |
字符串 | 引文标题。 |
url |
字符串 | 引文 URL。 |
publishedBy |
字符串 | 引用内容的Publisher。 |
hostPageUrl |
字符串 | 承载引用内容的页面的 URL。 |
lastUpdatedAt |
字符串 | 上次更新时间时间戳。 |
crawledAt |
字符串 | 爬网时间戳。 |
language |
字符串 | 内容语言。 |
isAdult |
boolean | 引文是否包含成人内容。 在将省略的字段视为false时true显式返回 。 |
特定于答案的引文还可以包括以下元数据:
| 领域 | 类型 | 适用对象 | 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。
| 领域 | 类型 | Description |
|---|---|---|
content |
字符串 | 结果的文本证据。 |
thumbnail |
对象(可选) | 包含 url (字符串)、 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 是一个图像对象。 源图像 URL、宿主页面 URL、标题和源日期在结果引文中提供(如果可用)。
| 内容字段 | 类型 | 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 是一个视频对象。 源详细信息(如视频标题、URL、发布者和源日期)在结果引文中提供(如果可用)。
| 内容字段 | 类型 | Description |
|---|---|---|
description |
字符串 | 视频内容的说明。 |
summary |
字符串 | 视频的简短摘要或突出显示。 |
viewCount |
整数 | 视频视图数。 |
length |
字符串 | 采用格式的视频持续时间 HH:MM:SS 。 |
allowHttpsEmbedding |
boolean | 是否允许 HTTPS 嵌入。 |
allowMobileEmbedding |
boolean | 是否允许移动嵌入。 |
embeddingUrl |
字符串 | 用于嵌入视频的 URL。 |
thumbnailUrl |
字符串 | 视频缩略图 URL。 |
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": []
}
}
VideoMoment
| 领域 | 类型 | Description |
|---|---|---|
title |
字符串 | 段标题。 |
description |
字符串 | 段的说明。 |
startTime |
字符串 | 以格式分段开始时间 d.hh:mm:ss 。 |
endTime |
字符串 | 以格式分段结束时间 d.hh:mm:ss 。 |
momentUrl |
字符串 | 直接指向段的 URL。 |
Weather 对象
当查询与天气有关时,自动可以返回每个位置的一个 structured/weather 结果。 字段包含在可用时。 一 units起读取数值度量;不假定固定单位系统。
| 内容字段 | 类型 | Description |
|---|---|---|
location |
字符串 | 位置名称,例如 Seattle, Washington。 |
url |
字符串 | 位置的天气属性 URL。 同一 URL 位于结果的引文中。 |
units |
对象 | 单位系统(system)和单位,用于temperature、speed、pressuredistance、、height和time。 |
alerts |
WeatherAlert 数组 | 按用户所在国家或地区筛选的位置的活动或最近的天气警报。 |
currentWeather |
对象 | 当前条件,包括condition、dayPeriod、、、universalThermalClimateIndexfeelsLikehumiditydewPointuvvisibilitytemperaturepressureuvLevel、windSpeed、、windDirection、、windGust以及airQualityobservedAt可用时间。 |
forecastedWeather |
对象数组 | 每日预报,包括validDate、condition、、temperatureHigh、feelsLikeLowfeelsLikeHightemperatureLowprecipitationChance、雨雪量、humidityday、nightalmanac、和hourly预测(如果可用)。 |
sunlight |
对象 | 当查询要求特定日期时,日出、日落、月亮、月亮和月相。 |
当前airQuality可以包含index、severity和 primaryPollutantvalidAt。 每日预测 humidity 可以包含 high 和 low。 其day和night子预测可以包含condition、precipitationChance和windSpeedwindDirection。 它 almanac 包含的 validDate太阳和月亮数据。
{
"type": "structured/weather",
"content": {
"location": "Seattle, Washington",
"units": {
"system": "Imperial",
"temperature": "F"
},
"currentWeather": {
"condition": "Cloudy",
"temperature": 50
}
}
}
WeatherAlert
| 领域 | 类型 | 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 |
TimeZoneEntry 数组 | 单位置或多位置时间应答的条目。 |
startTimeZone |
TimeZoneEntry | 比较的源时区。 |
endTimeZone |
TimeZoneEntry | 比较的目标时区。 |
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"
}
]
}
}
TimeZoneEntry
| 领域 | 类型 | Description |
|---|---|---|
timeZoneName |
字符串 | 完整时区名称。 |
timeZoneAbbreviation |
字符串 | 缩写,例如 PST 或 IST。 |
location |
字符串 | 与条目关联的城市、国家或地区。 |
utcOffset |
number | UTC 偏移量(以小时为单位)。 例如,可以是小数部分,也可以在 5.5不可用时省略。 |
utcTime |
字符串 | UTC 时间作为格式化字符串。 |
localTime |
字符串 | 本地时间作为格式化字符串。 |
时间字符串可以包含星期几前缀;不要假设它们是裸露的 ISO 8601 时间戳。
错误代码
| 状态代码 | Description |
|---|---|
| 200 | 请求成功,包括没有结果的有效搜索。 |
| 400 | 无效的参数或格式不正确的 JSON。 |
| 401 | 缺少或无效的身份验证凭据。 |
| 403 | 未为自动启用经过身份验证的 Web IQ AppID。 |
| 429 | 超出速率或配额限制。 |
| 500 | 内部服务失败。 |
| 503 | 所需的服务不可用。 |
| 504 | 请求超时。 |
有关共享错误架构和重试指南,请参阅 错误处理。