终结点：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 |
|---|---|---|---|---|
| 查询 | 是 | 字符串 | - | 新闻结果的搜索查询。 最大长度为 1000 个字符。 |
| maxResults | 否 | 整数 | 10 | 要返回的最大结果数。 默认值为 10。 最大值为 20。 |
| 语言 | 否 | 字符串 | “en” | 搜索结果中接口语言的 2 字母 ISO 639-1 语言代码。 有关完整列表，请参阅 “支持的语言 ”。 |
| 区域 | 否 | 字符串 | "US" | 结果应来自的 2 个字母国家/地区代码（例如“US”、“JP”、“GB”等）。 有关完整列表，请参阅 “支持的区域 ”。 |
| 位置 | 否 | 字符串 | - | 格式为“lat：<float>; 的位置信息;long：<float>“，例如”lat：40.753250;long：-74.003807”。 |
| contentFormat | 否 | 字符串 | 具有完整文档访问权限的“段落”（“text”） |
passage 返回与查询最相关的每个结果的各个部分（建议用于地面）。
text， html 并 markdown 返回完整文档，并仅适用于具有完整文档访问权限的应用程序;请参阅 段落和内容格式。 在每个请求上设置它。 |
| maxLength（最大长度） | 否 | 整数 | 3000 （具有完整文档访问权限的 10000） | 每个结果的最大字符 content 数，1 到 500000。 没有完全的文档访问权限， content 最多有 3000 个字符。 请参阅 默认值和限制。 在每个请求上设置它。 |
内容格式
设置为 contentFormat = passage 获取与查询最相关的每个结果部分，最多 maxLength 包含字符（3000 是一个很好的起点）。 这是用于地面的建议格式;请参阅 常见问题解答中的“什么是 passage”，为什么使用它 ？ 具有完整文档访问权限的应用程序也可以请求完整文档;texthtmlmarkdown对于其他应用程序，这些格式返回 HTTP 403。 请参阅 段落和内容格式。
请求标头
| 领域 | 类型 | Description |
|---|---|---|
| 主持人 | 字符串 | 适用于 Microsoft AI API 的主机：api.microsoft.ai. |
| x-apikey 或 授权 | 字符串 | API 密钥或Entra ID访问令牌进行身份验证。 |
| Content-Type | 字符串 | 请求正文的 MIME 类型。 使用 application/json。 |
响应
新闻响应
| 领域 | 类型 | Description |
|---|---|---|
| newsResults | newsResult 数组 | 新闻文章结果列表。 |
| instrumentationClickBase | 字符串 | 单击 ping 请求的基 URL。 在结果项中追加一个 instrumentationSuffix 值，以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 注意：还可以使用 URL 重定向记录用户单击。 启用重定向后，无需执行任何操作即可记录用户单击，并且 instrumentationClickBase 不会包含在响应中。 有关设置说明，请参阅 检测指南 。 |
| instrumentationCitationBase | 字符串 | LLM 日志 ping 请求的基 URL。 追加数据有效负载以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 |
| traceId | 字符串 | 用于调试的跟踪 ID。 |
newsResult
| 领域 | 类型 | Description |
|---|---|---|
| title | 字符串 | 新闻的标题。 |
| url | 字符串 | 新闻文章的源 URL。 对于启用了 URL 重定向的中国用户，此字段包含的重定向 URL 与 clickUrl. |
| 域 | 字符串 | 结果的目标主机。 仅针对启用了 URL 重定向的中国用户返回。 |
| 内容 | 字符串 | 新闻结果的详细网页内容（即地面）。 |
| 缩略图 | thumbnail 对象 | 新闻文章的缩略图。 |
| 最后更新时间 | 字符串 | 新闻的最后一个更新日期，采用 UTC ISO8601格式。 |
| crawledAt | 字符串 | 新闻的最后一个爬网日期遵循ISO8601格式。 |
| 语言 | 字符串 | 新闻文章的语言使用 ISO 639-1 语言代码。 |
| 源 | 字符串 | Publisher名称，如“USA TODAY |MSN“、”CNN“等。 |
| isAdult | boolean | 指示内容是否为成人。 |
| clickUrl | 字符串 | 通过必应代理单击的重定向 URL。 仅当启用单击重定向时才会显示。 |
| instrumentationSuffix | 字符串 | 要追加到此结果项的检测 ping URL 基的后缀。 用作检测 ping URL 和重定向的 clickUrl K 值。 启用检测 ping 时存在。 |
Note
lastUpdatedAt 字段是可选的 – 也就是说，你可能会看到此字段的空值。
缩略图
| 领域 | 类型 | Description |
|---|---|---|
| url | 字符串 | 缩略图的网址。 |
| 宽度 | 整数 | 缩略图的宽度（以像素为单位）。 |
| height | 整数 | 缩略图的高度（以像素为单位）。 |
Note
thumbnail 也是可选的响应对象 - 它可能不适用于某些新闻结果。
错误代码
| 状态代码 | 错误类别 | Description | 常见原因 |
|---|---|---|---|
| 200 | 成功 | 请求成功。 | - |
| 400 | 错误的请求 | 无效的请求参数。 | 缺少必填字段、无效参数值、格式不正确的 JSON |
| 401 | Unauthorized | 身份验证失败或缺失。 | API 密钥无效，缺少 x-apikey 标头 |
| 403 | 禁止 | 有效凭据但权限不足。 | API 密钥缺少所需的权限 |
| 410 | 不存在 (Gone) | 需要 HTTPS。 | 通过 HTTP 而不是 HTTPS 发出的请求 |
| 415 | 不支持的媒体类型 | 不支持内容类型。 | 缺少或不正确的内容类型标头 |
| 429 | 请求过多 | 超出速率限制。 | 时间范围内请求过多 |
| 500 | 内部服务器错误 | 意外的服务器错误。 | 临时服务器问题 |
| 503 | 服务不可用 | 服务暂时不可用。 | 维护或临时中断 |
| 504 | 网关超时 | 请求已超时。 | 上游服务超时 |
有关详细的错误处理指南，请参阅 错误处理。