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

小提示

在 Microsoft Ignite 2026 現場嗎?一站式找到所有 Web IQ 資源:文件、訓練、程式碼範例,以及如何聯絡團隊。

幾分鐘內完成你的第一個 Microsoft Web IQ API 呼叫。 搜尋網路,檢視回應內容,並從已知網址中擷取以查詢為重點的段落。 以下為選用範例,示範 Places Search。

如果你還沒有 Web IQ 資源,建議先用 Azure 入口網站或 Azure CLI 建立一個再繼續。

請在本頁頂端選擇一個 SDK 或 REST 範例,即可同步切換所有範例。 SDK 會幫你處理認證、重試和回應類型。

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

Prerequisites

Note

如果你的應用程式在中國運行,請呼叫 https://api.microsoftol.com/v3 而不是 https://api.microsoft.ai/v3 來使用搜尋端點。 在 REST 範例中,替換網址。 在建構 SDK 客戶端時,請用 Python base_url 參數、TypeScript baseUrl 的選項、Rust、WebIqClient::builder().base_url(...)Java WebIQClientOptions.builder().baseUrl(...)或 .NET WebIQClientOptions.BaseUrl 的屬性設定相同的基礎 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

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

2. 搜尋網頁

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

我們建議在每個請求中設定 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
  }'

使用 python -m pip install webiq==1.1.0 安裝 SDK(Python 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.1.0 安裝 SDK(Node.js 22.x 需為 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 webiq@1.1.0 和 cargo add tokio --features macros,rt-multi-thread。 將此範例儲存為 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.1.0</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.1.0。 將此範例儲存為 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. 理解回應

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

4. 選擇端點

從...開始 使用 你會得到什麼
一個問題或搜尋查詢 網路搜尋 具有與查詢相關內容的已排序頁面
特定的網址 瀏覽 從該頁面擷取內容
地點或在地企業查詢 地點 結構化的地點細節,如地址與營業時間
需要自動選擇答案類型的查詢 自動 透過 REST 含有結果範圍引文的類型化證據

常見的基礎化工作流程同時使用這兩個端點:搜尋相關來源,選擇結果網址,然後瀏覽該網址,擷取與後續問題相關的段落。

5. 從網址中擷取內容

當你已經知道想讀哪一頁時,使用 Browse。 設定 contentFormat 為 passage 並提供非空白 query ,以取得與你問題最相關的頁面部分。

liveCrawl: "fallback" 請求 Web IQ 在頁面尚未收錄於索引中時進行爬取。 即時爬蟲會受到發布者禮貌政策限制及可用性的限制;fallback 不保證實際執行爬取。

所有範例都要求以查詢為中心的段落,這是用於 grounding 的建議格式。 選取 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"
  }'

使用 python -m pip install webiq==1.1.0 安裝 SDK(Python 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.1.0 安裝 SDK(Node.js 22.x 需為 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 webiq@1.1.0 和 cargo add tokio --features macros,rt-multi-thread。 將此範例儲存為 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.1.0</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.1.0。 將此範例儲存為 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。 即時爬行可以返回 202retryAfter,時間戳為 ISO 8601 UTC;等待該時間點後,再發送相同請求。 完整回應規格請參閱 瀏覽 API 參考資料。

6. 搜尋地點(可選)

使用地點搜尋,以獲取有關當地商家及其他地點的結構化資訊。 SDK 範例使用步驟 2 中安裝的 1.1.0 套件。 端點: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;
});

用第二步的 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 參考資料。

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 中的時間(ISO 8601 UTC 時間戳記)後,再發送同樣的請求。

如有其他失敗情況,請儲存 traceId,並參見 錯誤處理。 若要聯絡 Web IQ 支援,請提供 traceId 和 App ID,或若沒有 AppID,請提供你的公司名稱與 Web IQ 資源名稱。

下一步