小窍门
在 Microsoft Ignite 2026 上?在一处即可找到所有 Web IQ 资源:文档、培训、代码示例以及如何联系团队。
在几分钟内进行第一次Microsoft Web IQ API 调用。 搜索 Web、检查响应,并从已知 URL 中提取以查询为中心的段落。 其他示例显示位置搜索和自动证据检索。
如果还没有 Web IQ 资源,请在继续之前使用 Azure 门户或Azure CLI创建一个。
选择此页面顶部的 SDK 或 REST 示例,即可同时切换所有示例。 SDK 会为你处理身份验证、重试和响应类型。
API 密钥是评估 Web IQ 的最快方法。 对于生产工作负荷,请使用Microsoft Entra ID。
Prerequisites
- 来自Profile Management的 Web IQ API 密钥。
Note
如果应用程序在中国运行,则调用 https://api.microsoftol.com/v3 而不是 https://api.microsoft.ai/v3 搜索终结点。 在 REST 示例中,替换 URL。 构造 SDK 客户端时,请使用 Python 的参数base_url、TypeScript baseUrl 选项、Rust WebIqClient::builder().base_url(...)选项、JavaWebIQClientOptions.builder().baseUrl(...)或.NETWebIQClientOptions.BaseUrl的属性设置相同的基 URL。 请参阅 基本 URL。
小窍门
更喜欢无需代码的引导式开始吗? 在 Web IQ 开发者门户中,按照 开始使用 操作:选择应用配置文件、创建 API 密钥、从 Playground 发送请求、复制生成的代码并检查使用情况。
1. 保存您的 API 密钥
将密钥放在环境变量中,这样,请求示例就无需重复写出密钥,也不用将其放入源代码中。
macOS 或 Linux
export WEBIQ_API_KEY="your-api-key"
Windows PowerShell
$env:WEBIQ_API_KEY="your-api-key"
Warning
不要将密钥提交到源代码管理,也不要在浏览器或客户端代码中公开密钥。 将生产凭据存储在机密管理器中。
2. 搜索网页
如果有问题或查询,并且希望 Web IQ 发现并对相关页面进行排序,请使用 Web 搜索。
我们建议在每个请求中设置maxResults = 10、contentFormat = passage和maxLength = 3000,作为优化的运行点。 在此处,可以根据用例微调这些设置。
终结点:POST https://api.microsoft.ai/v3/search/web
curl --request POST "https://api.microsoft.ai/v3/search/web" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "latest developments in retrieval augmented generation",
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000
}'
安装 SDK(python -m pip install webiq==1.2.1Python 3.11 或更高版本),然后运行:
import os
from webiq import WebIQClient
from webiq.types import ContentFormat
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
results = client.web.search(
"latest developments in retrieval augmented generation",
max_results=10,
content_format=ContentFormat.passage,
max_length=3000,
)
for result in results.webResults or []:
print(result.title, result.url)
使用 npm install @microsoft/webiq@1.2.1 安装 SDK(22.x 需 Node.js 22.18 或更高版本,或 24+)。 将此示例另存为 search.mts,并使用 node search.mts 运行它。
import { WebIQClient, ContentFormat } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const results = await client.web.search(
"latest developments in retrieval augmented generation",
{
maxResults: 10,
contentFormat: ContentFormat.PASSAGE,
maxLength: 3000,
},
);
for (const result of results.webResults ?? []) {
console.log(result.title, result.url);
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
在 Rust 1.88 或更高版本的项目中,运行 cargo add tokio --features macros,rt-multi-thread 和 cargo add webiq@1.2.1。 将此示例保存为 src/main.rs 并运行 cargo run。
use webiq::{ContentFormat, WebIqClient, WebSearchOptions};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let results = client.web().search(
"latest developments in retrieval augmented generation",
WebSearchOptions::new()
.max_results(10)
.content_format(ContentFormat::Passage)
.max_length(3000),
).await?;
for result in results.web_results.unwrap_or_default() {
println!("{:?} {:?}", result.title, result.url);
}
Ok(())
}
在为 Java 11 或更高版本配置的 Maven 项目中,将此依赖项添加到pom.xml:
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
将此示例保存为 src/main/java/Search.java 并运行 mvn compile exec:java -Dexec.mainClass=Search。
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.ContentFormat;
import com.microsoft.webiq.models.WebResponse;
import com.microsoft.webiq.models.WebResult;
import com.microsoft.webiq.resources.WebSearchOptions;
public class Search {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
WebResponse results = client.web.search(
"latest developments in retrieval augmented generation",
WebSearchOptions.builder()
.maxResults(10)
.contentFormat(ContentFormat.PASSAGE)
.maxLength(3000)
.build());
if (results.getWebResults() != null) {
for (WebResult result : results.getWebResults()) {
System.out.println(result.getTitle() + " " + result.getUrl());
}
}
}
}
}
在 .NET 8 或更高版本的控制台项目中,运行 dotnet add package Microsoft.WebIQ --version 1.2.1。 将此示例保存为 Program.cs 并运行 dotnet run。
using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var results = await client.Web.SearchAsync(
"latest developments in retrieval augmented generation",
request =>
{
request.MaxResults = 10;
request.ContentFormat = ContentFormat.Passage;
request.MaxLength = 3000;
});
foreach (var result in results.WebResults ?? [])
Console.WriteLine($"{result.Title} {result.Url}");
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/search/web",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "latest developments in retrieval augmented generation",
"maxResults": 10,
"contentFormat": "passage",
"maxLength": 3000,
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
将此示例另存为 search.mjs,并使用 node search.mjs 运行它。
const response = await fetch("https://api.microsoft.ai/v3/search/web", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "latest developments in retrieval augmented generation",
maxResults: 10,
contentFormat: "passage",
maxLength: 3000,
}),
});
if (!response.ok) {
throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
3. 了解响应
成功的 Web 搜索返回 webResults 数组。 此简略示例显示最常使用的字段:
{
"webResults": [
{
"title": "Example result",
"url": "https://example.com/article",
"content": "The query-relevant passage extracted from the page...",
"crawledAt": "2026-07-18T12:00:00Z"
}
],
"traceId": "00000000000000000000000000000000"
}
-
title和url识别来源。 -
content包含与查询相关的段落,因为该请求使用了contentFormat: "passage"。 -
traceId帮助 Web IQ 支持调查某个请求。
在 REST 响应和 MCP 工具结果中,省略具有 null 或空字符串("")值的模型字段,包括嵌套结果对象的字段;空列表/数组([])字段保留在 Places 中,其中列表字段也可以不存在。 将缺席字段视为不可用,将空或缺席列表视为没有项目。 保留仅包含空格的字符串、空字典、false、0、单独的数组/字典条目和嵌入的原始 JSON。 根数组和协议信封集合(如 MCP content )保持不变。
有关所有参数和响应字段,请参阅 Web 搜索 API 参考 。
4.选择终结点
| 从...开始 | Use | 您将获得的内容 |
|---|---|---|
| 问题或搜索查询 | Web 搜索 | 具有与查询相关内容的排名靠前的页面 |
| 特定 URL | 浏览 | 从该页中提取的内容 |
| 地点或本地业务查询 | 地点 | 结构化地点详细信息,如地址和营业时间 |
| 需要自动选择答案类型的查询 | 通过 REST 或 SDK 1.2.1 及更高版本自动 | 带有结果范围引文的类型化证据 |
通用地面工作流使用这两个终结点:搜索相关源,选择结果 URL,然后浏览该 URL 以提取与后续问题相关的段落。
5. 从 URL 中提取内容
当您已经知道要阅读哪个页面时,使用“浏览”。
passage设置为contentFormat并提供非空白query,以检索与问题最相关的页面部分。
liveCrawl: "fallback" 请求 Web IQ 在索引中尚不可用时抓取该页面。 实时爬网受发布方限制抓取频率的规则和可用性的约束;fallback 不保证会发生实际抓取行为。
所有示例都请求以查询为中心的段落,这是用于提供依据的推荐格式。 所选内容 query 必须是非空白且不超过 1000 个字符; maxLength 单独控制返回的内容量。 完整文档格式(text、html和markdown)需要完全的文档访问权限。
终结点:POST https://api.microsoft.ai/v3/browse
curl --request POST "https://api.microsoft.ai/v3/browse" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
"query": "How fast is Web IQ",
"contentFormat": "passage",
"maxLength": 3000,
"liveCrawl": "fallback"
}'
安装 SDK(python -m pip install webiq==1.2.1Python 3.11 或更高版本),然后运行:
import os
from webiq import WebIQClient
from webiq.types import BrowseContentFormat
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
page = client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
query="How fast is Web IQ",
content_format=BrowseContentFormat.passage,
max_length=3000,
live_crawl="fallback",
)
print(page.content)
使用 npm install @microsoft/webiq@1.2.1 安装 SDK(22.x 需 Node.js 22.18 或更高版本,或 24+)。 将此示例另存为 browse.mts,并使用 node browse.mts 运行它。
import { WebIQClient, BrowseContentFormat, LiveCrawlMode } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const page = await client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
{
query: "How fast is Web IQ",
contentFormat: BrowseContentFormat.PASSAGE,
maxLength: 3000,
liveCrawl: LiveCrawlMode.FALLBACK,
},
);
console.log(JSON.stringify(page, null, 2));
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
在 Rust 1.88 或更高版本的项目中,运行 cargo add tokio --features macros,rt-multi-thread 和 cargo add webiq@1.2.1。 将此示例保存为 src/main.rs 并运行 cargo run。
use webiq::{BrowseContentFormat, BrowseOptions, LiveCrawlMode, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let page = client.browse().fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
BrowseOptions::new()
.query("How fast is Web IQ")
.content_format(BrowseContentFormat::Passage)
.max_length(3000)
.live_crawl(LiveCrawlMode::Fallback),
).await?;
println!("{}", page.content.unwrap_or_default());
Ok(())
}
在为 Java 11 或更高版本配置的 Maven 项目中,将此依赖项添加到pom.xml:
<dependency>
<groupId>com.microsoft.webiq</groupId>
<artifactId>webiq</artifactId>
<version>1.2.1</version>
</dependency>
将此示例保存为 src/main/java/Browse.java 并运行 mvn compile exec:java -Dexec.mainClass=Browse。
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.BrowseContentFormat;
import com.microsoft.webiq.models.BrowseResponse;
import com.microsoft.webiq.models.LiveCrawlMode;
import com.microsoft.webiq.resources.BrowseFetchOptions;
public class Browse {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
BrowseResponse page = client.browse.fetch(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
BrowseFetchOptions.builder()
.query("How fast is Web IQ")
.contentFormat(BrowseContentFormat.PASSAGE)
.maxLength(3000)
.liveCrawl(LiveCrawlMode.FALLBACK)
.build());
System.out.println(page.getContent());
}
}
}
在 .NET 8 或更高版本的控制台项目中,运行 dotnet add package Microsoft.WebIQ --version 1.2.1。 将此示例保存为 Program.cs 并运行 dotnet run。
using Microsoft.WebIQ;
using Microsoft.WebIQ.Models;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var page = await client.Browse.FetchAsync(
"https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
request =>
{
request.ContentFormat = BrowseContentFormat.Passage;
request.Query = "How fast is Web IQ";
request.MaxLength = 3000;
request.LiveCrawl = LiveCrawlMode.Fallback;
});
Console.WriteLine(page.Content);
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/browse",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
"query": "How fast is Web IQ",
"contentFormat": "passage",
"maxLength": 3000,
"liveCrawl": "fallback",
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
将此示例另存为 browse.mjs,并使用 node browse.mjs 运行它。
const response = await fetch("https://api.microsoft.ai/v3/browse", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
url: "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
query: "How fast is Web IQ",
contentFormat: "passage",
maxLength: 3000,
liveCrawl: "fallback",
}),
});
if (!response.ok) {
throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
成功的 200 响应包括页面 url、title、提取的 content 和一个 traceId。 实时爬网可以返回带有 retryAfter 的 202,即 ISO 8601 UTC 时间戳;等到该时间,然后再次发送相同的请求。 有关完整的响应约定,请参阅 浏览 API 参考。
6. 搜索地点(可选)
使用“地点搜索”获取有关本地企业和其他地点的结构化信息。 SDK 示例使用步骤 2 中安装的 1.2.1 包。
终结点:POST https://api.microsoft.ai/v3/search/places
curl --request POST "https://api.microsoft.ai/v3/search/places" \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "coffee in Seattle",
"maxResults": 5,
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321"
}'
import os
from webiq import WebIQClient
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
places = client.places.search(
"coffee in Seattle",
max_results=5,
language="en",
region="US",
location="lat:47.6062;long:-122.3321",
)
for place in places.placeResults or []:
print(place.name, place.businessUrl)
将此示例另存为 places.mts,并使用 node places.mts 运行它。
import { WebIQClient } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const places = await client.places.search("coffee in Seattle", {
maxResults: 5,
language: "en",
region: "US",
location: "lat:47.6062;long:-122.3321",
});
for (const place of places.placeResults ?? []) {
console.log(place.name, place.businessUrl);
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
使用步骤 2 中的 Tokio 设置。 将此示例保存为 src/main.rs 并运行 cargo run。
use webiq::{PlacesSearchOptions, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let places = client.places().search(
"coffee in Seattle",
PlacesSearchOptions::new()
.max_results(5)
.language("en")
.region("US")
.location("lat:47.6062;long:-122.3321"),
).await?;
for place in places.place_results.unwrap_or_default() {
println!("{:?} {:?}", place.name, place.business_url);
}
Ok(())
}
在步骤 2 的 Maven 项目中,将此示例保存为 src/main/java/Places.java,并运行 mvn compile exec:java -Dexec.mainClass=Places。
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.PlaceItem;
import com.microsoft.webiq.models.PlacesResponse;
import com.microsoft.webiq.resources.PlacesSearchOptions;
public class Places {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
PlacesResponse places = client.places.search("coffee in Seattle",
PlacesSearchOptions.builder().maxResults(5)
.language("en").region("US")
.location("lat:47.6062;long:-122.3321").build());
if (places.getPlaceResults() != null) {
for (PlaceItem place : places.getPlaceResults()) {
System.out.println(place.getName() + " " + place.getBusinessUrl());
}
}
}
}
}
在步骤 2 的 .NET 控制台项目中,将此示例另存为Program.cs并运行dotnet run。
using Microsoft.WebIQ;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var places = await client.Places.SearchAsync("coffee in Seattle", request =>
{
request.MaxResults = 5;
request.Language = "en";
request.Region = "US";
request.Location = "lat:47.6062;long:-122.3321";
});
foreach (var place in places.PlaceResults ?? [])
Console.WriteLine($"{place.Name} {place.BusinessUrl}");
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/search/places",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "coffee in Seattle",
"maxResults": 5,
"language": "en",
"region": "US",
"location": "lat:47.6062;long:-122.3321",
},
timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
将此示例另存为 places.mjs,并使用 node places.mjs 运行它。
const response = await fetch("https://api.microsoft.ai/v3/search/places", {
method: "POST",
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "coffee in Seattle",
maxResults: 5,
language: "en",
region: "US",
location: "lat:47.6062;long:-122.3321",
}),
});
if (!response.ok) {
throw new Error(`Places failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
从 placeResults中读取结果。 列表和单个字段可以不存在,因此在使用地址、营业时间或其他详细信息之前检查缺失值。 请参阅 Places API 参考。
7. 使用 Auto 检索证据
当希望 Web IQ 选择检索源并返回带有支持引文的类型化证据时,请使用“自动”。 提出完整的自然语言问题,保留相关约束,如日期、位置和单位。 这些示例省略了 mode,以使用默认值,并允许每个请求尝试 60 秒。 如果您在处理复杂问题时需要更全面的检索,请将 mode 设置为 advanced,以用于 Auto Advanced。
自动返回供你的应用程序使用的证据,而不是生成的最终答案。 阅读每个证据结果时查看其各自的引文;不要将一个结果中的引文视为对另一个结果的支持。 SDK 示例使用步骤 2 中安装的所有五个 SDK 的版本 1.2.1。
终结点:POST https://api.microsoft.ai/v3/auto
curl --request POST "https://api.microsoft.ai/v3/auto" \
--max-time 60 \
--header "x-apikey: $WEBIQ_API_KEY" \
--header "content-type: application/json" \
--data '{
"query": "What are the latest developments in retrieval-augmented generation?",
"maxResponseLength": 30000,
"maxCitations": 5
}'
import os
from webiq import WebIQClient
with WebIQClient(api_key=os.environ["WEBIQ_API_KEY"]) as client:
evidence = client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
max_response_length=30000,
max_citations=5,
timeout=60.0,
)
for result in evidence.results or []:
print(result.evidence)
for citation in result.citations or []:
print(citation.title, citation.url)
将此示例另存为 auto.mts,并使用 node auto.mts 运行它。
import { WebIQClient } from "@microsoft/webiq";
async function main() {
const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });
try {
const evidence = await client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
{ maxResponseLength: 30000, maxCitations: 5, timeout: 60_000 },
);
for (const result of evidence.results ?? []) {
console.log(result.evidence);
for (const citation of result.citations ?? []) {
console.log(citation.title, citation.url);
}
}
} finally {
await client.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
使用步骤 2 中的 Tokio 设置。 将此示例保存为 src/main.rs 并运行 cargo run。
use webiq::{AutoSearchOptions, WebIqClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = WebIqClient::new(std::env::var("WEBIQ_API_KEY")?)?;
let evidence = client.auto().search(
"What are the latest developments in retrieval-augmented generation?",
AutoSearchOptions::new()
.max_response_length(30000)
.max_citations(5)
.timeout(std::time::Duration::from_secs(60)),
).await?;
for result in evidence.results.unwrap_or_default() {
println!("{:?}", result.evidence);
for citation in result.citations.unwrap_or_default() {
println!("{:?} {:?}", citation.title, citation.url);
}
}
Ok(())
}
在步骤 2 的 Maven 项目中,将此示例保存为 src/main/java/Auto.java,并运行 mvn compile exec:java -Dexec.mainClass=Auto。
import com.microsoft.webiq.WebIQClient;
import com.microsoft.webiq.models.AutoEvidenceCitation;
import com.microsoft.webiq.models.AutoEvidenceResult;
import com.microsoft.webiq.models.SearchAutoEvidenceResponse;
import com.microsoft.webiq.resources.AutoSearchOptions;
public class Auto {
public static void main(String[] args) {
try (WebIQClient client = WebIQClient.withApiKey(System.getenv("WEBIQ_API_KEY"))) {
SearchAutoEvidenceResponse evidence = client.auto.search(
"What are the latest developments in retrieval-augmented generation?",
AutoSearchOptions.builder()
.maxResponseLength(30000).maxCitations(5)
.timeout(java.time.Duration.ofSeconds(60)).build());
if (evidence.getResults() != null) {
for (AutoEvidenceResult result : evidence.getResults()) {
System.out.println(result.getEvidence());
if (result.getCitations() != null) {
for (AutoEvidenceCitation citation : result.getCitations()) {
System.out.println(citation.getTitle() + " " + citation.getUrl());
}
}
}
}
}
}
}
在步骤 2 的 .NET 控制台项目中,将此示例另存为Program.cs并运行dotnet run。
using Microsoft.WebIQ;
using System.Text.Json;
string apiKey = Environment.GetEnvironmentVariable("WEBIQ_API_KEY")
?? throw new InvalidOperationException("Set WEBIQ_API_KEY before running this example.");
using var client = new WebIQClient(apiKey);
var evidence = await client.Auto.SearchAsync(
"What are the latest developments in retrieval-augmented generation?",
request =>
{
request.MaxResponseLength = 30000;
request.MaxCitations = 5;
}, timeout: TimeSpan.FromSeconds(60));
foreach (var result in evidence.Results ?? [])
{
Console.WriteLine(JsonSerializer.Serialize(result.Evidence));
foreach (var citation in result.Citations ?? [])
Console.WriteLine($"{citation.Title} {citation.Url}");
}
import os
import json
import requests
response = requests.post(
"https://api.microsoft.ai/v3/auto",
headers={
"x-apikey": os.environ["WEBIQ_API_KEY"],
"content-type": "application/json",
},
json={
"query": "What are the latest developments in retrieval-augmented generation?",
"maxResponseLength": 30000,
"maxCitations": 5,
},
timeout=60,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
将此示例另存为 auto.mjs,并使用 node auto.mjs 运行它。
const response = await fetch("https://api.microsoft.ai/v3/auto", {
method: "POST",
signal: AbortSignal.timeout(60_000),
headers: {
"x-apikey": process.env.WEBIQ_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
query: "What are the latest developments in retrieval-augmented generation?",
maxResponseLength: 30000,
maxCitations: 5,
}),
});
if (!response.ok) {
throw new Error(`Auto failed: ${response.status} ${await response.text()}`);
}
console.log(JSON.stringify(await response.json(), null, 2));
成功的响应包含一个 results 数组。 每个结果都将一个类型化的evidence对象与其支持的citations配对。 空的或缺失的 results 数组没有要处理的证据。 有关证据类型、响应示例和请求限制,请参阅 Auto API reference。
Troubleshooting
| Status | 需要检查的事项 |
|---|---|
401 Unauthorized |
确认 WEBIQ_API_KEY 已设置,请求在 x-apikey 标头中发送它。 |
415 Unsupported Media Type |
发送 content-type: application/json。 |
429 Too Many Requests |
重试前请等待,并降低请求频率。 |
浏览 404 Not Found |
确认该 URL 可公开访问且有效。 当索引内容可能不可用时使用 liveCrawl: "fallback" 。 |
浏览 202 Accepted |
等待直到 retryAfter 中的时间(ISO 8601 UTC 时间戳),然后再次发送相同的请求。 |
自动 403 Forbidden |
检查是否在配置文件管理中的允许的服务下列出了 Auto。 如果不是,请使用 AppID 打开 Web IQ 支持请求 。 |
对于其他失败,请保存 traceId 并查看 错误处理。 若要联系 Web IQ 支持部门,请提供 traceId 和您的 AppID;如果您没有 AppID,请提供您的公司名称和 Web IQ 资源名称。
后续步骤
- 浏览 Web 搜索 和 浏览 API 参考。
- 使用 Places 检索结构化本地商家数据,或使用 Auto 获取自动选择的证据。
- 使用 Python、TypeScript、Rust、Java 和 .NET SDK。
- 在 Claude Code、Cursor 或 VS Code 中安装 MCP 服务器 。
- 使用 Microsoft Entra ID 设置生产身份验证。
- 在 GitHub 上运行 Web IQ 代码示例中的完整示例。
- 参加培训模块使用 Web IQ 将基于 Web 的知识集成到你的代理中。
- 观看让代理基于现实世界信息,这是 Microsoft IQ 系列的 Web IQ 一集。