Web 搜索 REST API 参考

终结点：POST https://api.microsoft.ai/v3/search/web

示例请求：

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

参数	Required	类型	Default	Description
查询	是	字符串	-	搜索查询字符串。 最大长度为 1000 个字符。 支持“site：”和“-site：”运算符，以包含或排除来自特定网站的结果（例如“查询site:example.com”）。 仅在必要时使用这些运算符，因为它们本质上会降低结果相关性。
maxResults	否	整数	10	要返回的最大结果数。 默认值为 10，最大值为 50。
语言	否	字符串	“en”	搜索结果中接口语言的 2 字母 ISO 639-1 语言代码。 有关完整列表，请参阅 “支持的语言 ”。
区域	否	字符串	"US"	结果应来自的 2 个字母国家/地区代码（例如“US”、“JP”、“GB”等）。 有关完整列表，请参阅 “支持的区域 ”。
位置	否	字符串	-	格式为“lat：<float>; 的位置信息;long：<float>“，例如”lat：40.753250;long：-74.003807”。 如果未指定，则会推断查询中的位置。
contentFormat	否	字符串	具有完整文档访问权限的“段落”（“html”）	passage 返回与查询最相关的每个结果的各个部分（建议用于地面）。 text， html 并 markdown 返回完整文档，并仅适用于具有完整文档访问权限的应用程序;请参阅 段落和内容格式。 在每个请求上设置它。 注意：Web API 不返回字段 snippet 。
maxLength（最大长度）	否	整数	3000 （具有完整文档访问权限的 10000）	每个结果的最大字符 content 数，1 到 500000。 没有完全的文档访问权限， content 最多有 3000 个字符。 请参阅 默认值和限制。 在每个请求上设置它。
safeSearch	否	字符串	“strict”	安全搜索筛选级别。 值：“off”、“strict”。 默认值为“strict”。

内容格式

设置为 contentFormat = passage 获取与查询最相关的每个结果部分，最多 maxLength 包含字符（3000 是一个很好的起点）。 这是用于地面的建议格式;请参阅 常见问题解答中的“什么是 passage”，为什么使用它 ？ 具有完整文档访问权限的应用程序也可以请求完整文档;texthtmlmarkdown对于其他应用程序，这些格式返回 HTTP 403。 请参阅 段落和内容格式。

SafeSearch

SafeSearch 模式允许你在返回结果之前控制 Web API 筛选掉的敏感 Web 内容量。 敏感内容包括暴力、自我伤害和其他类别。 默认值为 strict。

Value	Description	建议用于
strict	阻止与成人、猥亵、暴力、仇恨和自残主题相关的内容。	儿童安全、教育、消费者/保守部署。
off	仍然阻止非法内容。 对于其他可能有害的内容，将最终筛选的责任转移到用户。	研究、分析、选择加入企业、高级 3P 用例。

Note

如果使用 site: 查询运算符，则无论值如何 safeSearch ，响应都可能包含成人内容。 site:仅当知道网站上的内容并且你的方案支持成人内容的可能性时使用。

请求标头

领域	类型	Description
主持人	字符串	适用于 Microsoft AI API 的主机：api.microsoft.ai.
x-apikey 或 授权	字符串	API 密钥或Entra ID访问令牌进行身份验证。
Content-Type	字符串	请求正文的 MIME 类型。 使用 application/json。

响应

Web 响应

领域	类型	Description
webResults	webResult 数组	网页结果列表。
querySignals	querySignals	搜索查询的查询级别排名信号。
riskLevel	字符串	针对查询评估的安全风险级别。 可能的值：low、moderate、、highveryHigh。
instrumentationClickBase	字符串	单击 ping 请求的基 URL。 在结果项中追加一个 instrumentationSuffix 值，以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 注意：还可以使用 URL 重定向记录用户单击。 启用重定向后，无需执行任何操作即可记录用户单击，并且 instrumentationClickBase 不会包含在响应中。 有关设置说明，请参阅 检测指南 。
instrumentationCitationBase	字符串	LLM 日志 ping 请求的基 URL。 追加数据有效负载以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。
traceId	字符串	用于调试的跟踪 ID。

querySignals

领域	类型	Description
freshness	boolean	指示是否应将新文档优先于此查询的其他文档。

webResult

领域	类型	Description
title	字符串	网页的标题。
url	字符串	网页的源 URL。 对于启用了 URL 重定向的中国用户，此字段包含的重定向 URL 与 clickUrl.
域	字符串	结果的目标主机。 仅针对启用了 URL 重定向的中国用户返回。
内容	字符串	网页的详细内容（即地面）。
crawledAt	字符串	网页的最后一个已爬网日期遵循ISO8601格式。
最后更新时间	字符串	网页的上次更新时间遵循ISO8601格式。
语言	字符串	网页的语言使用 ISO 639-1 语言代码。
isAdult	boolean	指示结果是否包括成人内容。
clickUrl	字符串	通过必应代理单击的重定向 URL。 仅当启用单击重定向时才会显示。
instrumentationSuffix	字符串	要追加到此结果项的检测 ping URL 基的后缀。 用作检测 ping URL 和重定向的 clickUrl K 值。 启用检测 ping 时存在。
contentTier	字符串	结果的内容层，描述内容源的商业访问特征。 可能的值： standard （默认服务产品/服务提供的所有客户可用的标准内容）、 entitled （通过现有客户许可协议提供的内容（包括自 带许可（BYOL） 内容，客户直接从发布者获得许可，并通过自己的合同安排进行访问）， premium （提供超出标准产品/服务的附加价值的高级内容，并接受计费）。

Note

crawledAt值和lastUpdatedAt字段是可选的。 也就是说，他们的报道不是100%。 你可能会看到这些字段的空值。

错误代码

状态代码	错误类别	Description	常见原因
200	成功	请求成功。	-
400	错误的请求	无效的请求参数。	缺少必填字段、无效参数值、格式不正确的 JSON
401	Unauthorized	身份验证失败或缺失。	API 密钥无效，缺少 x-apikey 标头
403	禁止	有效凭据但权限不足。	API 密钥缺少所需的权限
410	不存在 (Gone)	需要 HTTPS。	通过 HTTP 而不是 HTTPS 发出的请求
415	不支持的媒体类型	不支持内容类型。	缺少或不正确的内容类型标头
429	请求过多	超出速率限制。	时间范围内请求过多
500	内部服务器错误	意外的服务器错误。	临时服务器问题
503	服务不可用	服务暂时不可用。	维护或临时中断
504	网关超时	请求已超时。	上游服务超时

有关详细的错误处理指南，请参阅 错误处理。

---

另请参阅：视频搜索 | 浏览 | 新闻搜索图像搜索 | | MCP