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

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

选择 REST API 示例或下面的 Python 或 TypeScript SDK 示例。 Python和 TypeScript SDK 负责处理身份验证、重试和响应类型。

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 --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（pip install webiqPython 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 安装 SDK（Node.js 22.18 或更高版本）。将此示例另存为 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;
});

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

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

4.选择 Web 搜索或浏览

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

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

5. 从 URL 中提取内容

当您已经知道要阅读哪个页面时，使用“浏览”。 liveCrawl: "fallback" 请求 Web IQ 在索引中尚不可用时抓取该页面。实时爬网受发布方限制抓取频率的规则和可用性的约束；fallback 不保证会发生实际抓取行为。

终结点：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://news.microsoft.com/source/",
    "contentFormat": "markdown",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

安装 SDK（pip install webiqPython 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://news.microsoft.com/source/",
        content_format=BrowseContentFormat.markdown,
        max_length=3000,
        live_crawl="fallback",
    )
    print(page.content)

使用 npm install @microsoft/webiq 安装 SDK（Node.js 22.18 或更高版本）。将此示例另存为 browse.mts，并使用 node browse.mts 运行它。

import { WebIQClient, BrowseContentFormat } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const page = await client.browse.fetch(
      "https://news.microsoft.com/source/",
      {
        contentFormat: BrowseContentFormat.MARKDOWN,
        maxLength: 3000,
        liveCrawl: "fallback",
      },
    );
    console.log(JSON.stringify(page, null, 2));
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

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

将此示例另存为 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 设置生产身份验证。

反馈

此页面是否有帮助？

上次更新时间为 2026-11-02