快速入门：进行第一次 Web IQ API 调用

在几分钟内进行第一次Microsoft Web IQ REST API 调用。 你将搜索 Web、检查响应，然后从已知 URL 中提取内容。

API 密钥是评估 Web IQ 的最快方法。 对于生产工作负荷，请使用Microsoft Entra ID。

Prerequisites

• 来自Profile Management的 Web IQ API 密钥。

小窍门

使用 Web IQ Playground 从浏览器发送请求，并在 cURL、Python、JavaScript、C#、Java、Go 和 Ruby 中生成代码。

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

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
  }'

Python

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))

JavaScript

将此示例另存为 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、空字符串（""）或空列表/数组（[]）的模型字段将被省略，包括嵌套结果对象的字段。 将缺失的字符串字段视为不可用，将缺失的列表字段视为没有项。 保留仅包含空格的字符串、空字典、false、0、单独的数组/字典条目和嵌入的原始 JSON。 根数组和协议信封集合（如 MCP content ）保持不变。

有关所有参数和响应字段，请参阅 Web 搜索 API 参考 。

4.选择 Web 搜索或浏览

从...开始	Use	您将获得的内容
问题或搜索查询	Web 搜索	具有与查询相关内容的排名靠前的页面
特定 URL	浏览	从该页中提取的内容

一种常见的 grounding 工作流会同时使用这两个端点：搜索相关来源，选择一个结果 URL，然后在需要更完整的页面内容时浏览该 URL。

5. 从 URL 中提取内容

当您已经知道要阅读哪个页面时，使用“浏览”。 liveCrawl: "fallback" 请求 Web IQ 在索引中尚不可用时抓取该页面。

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

cURL

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://news.microsoft.com/source/",
    "contentFormat": "markdown",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

Python

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://news.microsoft.com/source/",
        "contentFormat": "markdown",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

将此示例另存为 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://news.microsoft.com/source/",
    contentFormat: "markdown",
    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。 实时爬网可以返回202及retryAfter；等待该持续时间，然后再次发送相同的请求。 有关完整的响应约定，请参阅 浏览 API 参考。

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 时长，然后重试相同的请求。

对于其他故障，请保存traceId文件并查看错误处理，或联系Web IQ 支持部门。

后续步骤

• 浏览 Web 搜索 和 浏览 API 参考。
• 使用 Python 和 TypeScript SDK。
• 在 Claude Code、Cursor 或 VS Code 中安装 MCP 服务器 。
• 使用 Microsoft Entra ID 设置生产身份验证。