クイック スタート: 初めての Web IQ API 呼び出しを行う

数分で Microsoft Web IQ REST API を初めて呼び出せます。 Web を検索し、応答を調べ、既知の URL からコンテンツを抽出します。

API キーは、Web IQ を評価する最速の方法です。 運用ワークロードの場合は、Microsoft Entra IDを使用します。

Prerequisites

• プロファイル管理からの 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 を検索する

質問やクエリがあり、Web IQ に関連するページを検出してランク付けさせたい場合は、Web Search を使用します。

最適化された動作点として、すべての要求に 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 Search が成功すると、 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 (null)、空の文字列 ("")、または空のリスト/配列 ([]) の値を持つモデル フィールドは省略されます。 存在しない文字列フィールドは利用不可として扱い、存在しないリスト フィールドはアイテムがないものとして扱います。 空白のみの文字列、 false、 0、空のディクショナリ、個々の配列/ディクショナリ エントリ、埋め込み生 JSON は保持されます。 ルート配列と MCP content のようなプロトコル エンベロープ コレクションは変更されません。

すべてのパラメーターと応答フィールドについては、 Web Search API リファレンスを参照 してください。

4. [Web 検索] または [参照...] を選択する

次から開始	Use	受け取るもの
質問または検索クエリ	Web 検索	クエリに関連するコンテンツを含むランク付けされたページ
特定の URL	ブラウズ	そのページから抽出されたコンテンツ

一般的なグラウンディングのワークフローでは、両方のエンドポイントが使用されます。関連するソースを検索し、結果の URL を選択してから、より完全なページ コンテンツが必要な場合は、その URL を参照します。

5. URL からコンテンツを抽出する

読みたいページがすでにわかっている場合は、[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を返すことができます。その期間待機してから、同じ要求をもう一度送信します。 完全な応答コントラクトについては、Browse 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 Search と Browse API のリファレンスを確認します。
• Python SDK と TypeScript SDK を使用します。
• Claude Code、Cursor、または VS Code に MCP サーバー をインストールします。
• Microsoft Entra IDを使用して運用認証を設定します。