快速入門：進行你的第一個 Web IQ API 呼叫

幾分鐘內，請進行您的第一次 Microsoft Web IQ REST API 呼叫。 你將搜尋網路，檢查回應，然後從已知網址擷取內容。

API 金鑰是評估 Web IQ 最快的方法。 對於生產工作負載，請使用 Microsoft Entra ID。

Prerequisites

小提示

使用 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

不要將你的金鑰提交到版本控制中，也不要在瀏覽器或客戶端程式碼中公開。 將生產憑證儲存在一個 Secret Manager 中。

2. 搜尋網頁

當你有問題或查詢，並希望 Web IQ 能發現並為相關頁面排序時，請使用網頁搜尋。

我們建議在每個請求中設定 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. 理解回應

成功的網路搜尋會回傳一個 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 Search API 參考資料 以獲得所有參數與回應欄位。

4. 選擇網頁搜尋或瀏覽

從...開始 使用 你會得到什麼
一個問題或搜尋查詢 網路搜尋 具有與查詢相關內容的已排序頁面
特定的網址 瀏覽 從該頁面擷取內容

常見的 grounding 工作流程同時使用這兩個端點：搜尋相關來源，選擇結果 URL，然後在需要更完整頁面內容時瀏覽該 URL。

5. 從網址中擷取內容

當你已經知道想讀哪一頁時，使用 Browse。 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 確認該網址是公開且有效的。 當已索引內容可能無法取得時使用 liveCrawl: "fallback" 。
瀏覽 202 Accepted 等待回傳的 retryAfter 持續時間後，再重新嘗試同一個請求。

其他失敗，請儲存traceId，並參見錯誤處理，或聯絡Web IQ 支援。

下一步

  • 上次更新時間：