小提示
在 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
- 來自 Profile Management 的 Web IQ API 金鑰。
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 資源名稱。
下一步
- 探索 網頁搜尋 與 瀏覽 API 參考資料。
- 用 Places 檢索結構化的在地企業資料,或用 Auto 自動選取的證據。
- 可以使用 Python、TypeScript、Rust、Java 和 .NET SDK。
- 請以 Claude Code、Cursor 或 VS Code 安裝 MCP 伺服器。
- 用 Microsoft Entra ID 設定正式環境驗證。
- 從 GitHub 上的 Web IQ 程式碼範例中執行完整範例。
- 參加訓練模組 :將網路知識整合進你的代理程式中,結合 Web IQ。
- 觀看《讓代理程式具備真實世界智慧》,這是 Microsoft IQ 系列的 Web IQ 集數。