Začínáme: Proveďte první volání rozhraní Web IQ API

Během několika minut proveďte první volání webového rozhraní REST API Microsoft Web IQ. Prohledáte web, zkontrolujete odpověď a pak extrahujete obsah ze známé adresy URL.

Klíče rozhraní API představují nejrychlejší způsob, jak vyhodnotit webové IQ. Pro produkční úlohy použijte Microsoft Entra ID.

Prerequisites

Tip

Pomocí web IQ Playground můžete odesílat požadavky z prohlížeče a generovat kód v cURL, Python, JavaScript, C#, Java, Go a Ruby.

1. Uložte svůj klíč API

Vložte klíč do proměnné prostředí, aby se neopakoval ani neumisťoval do zdrojového kódu.

macOS nebo Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

$env:WEBIQ_API_KEY="your-api-key"

Warning

Nezařaďte svůj klíč do správy zdrojového kódu ani ho nezpřístupňujte v prohlížeči nebo v kódu na straně klienta. Uložte produkční přihlašovací údaje ve správci tajných údajů.

2. Hledání na webu

Vyhledávání na webu použijte, pokud máte otázku nebo dotaz a chcete, aby Web IQ zjistil a seřadil relevantní stránky.

Doporučujeme nastavit maxResults = 10, contentFormat = passage a maxLength = 3000 u každého požadavku jako optimální provozní nastavení. Odsud můžete tato nastavení vyladit podle konkrétního použití.

Koncový bod: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

Uložte tento příklad jako search.mjs a spusťte ho s 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. Pochopení odpovědi

Úspěšné vyhledávání na webu vrátí webResults pole. Tento zkrácený příklad ukazuje pole, která budete nejčastěji používat:

{
  "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 a url identifikují zdroj.
  • content obsahuje úsek relevantní pro dotaz, protože byl použit požadavek contentFormat: "passage".
  • traceId pomáhá Web IQ Support prozkoumat žádost.

V odpovědích REST a výsledcích nástroje MCP jsou vynechána pole modelu s hodnotou null, prázdným řetězcem ("") nebo prázdným seznamem/polem ([]), včetně polí vnořených výsledných objektů. Považovat chybějící řetězcové pole za nedostupné a chybějící pole seznamu za pole bez položek. Řetězce obsahující pouze bílé znaky, false, 0, prázdné slovníky, jednotlivé položky pole/slovníku a vložené nezpracované JSON se zachovají. Kořenová pole a kolekce typu protocol-envelope, jako je MCP content, se nemění.

Informace o všech parametrech a polích odpovědi najdete v referenčních informacích k rozhraní API pro vyhledávání na webu .

4. Zvolte Vyhledávání na webu nebo Procházení.

Začíná na Použít Co získáte
Dotaz nebo vyhledávací dotaz Vyhledávání na webu Seřazené stránky s obsahem relevantním pro dotazy
Konkrétní adresa URL Procházet Extrahovaný obsah z této stránky

Běžný postup groundingu používá oba koncové body: vyhledejte relevantní zdroje, vyberte adresu URL výsledku a pak tuto adresu URL otevřete, když potřebujete podrobnější obsah stránky.

5. Extrahování obsahu z adresy URL

Funkci Procházet použijte, pokud už víte, kterou stránku chcete přečíst. liveCrawl: "fallback" požádá Web IQ, aby stránku procházel, pokud ještě není v indexu k dispozici.

Koncový bod: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

Uložte tento příklad jako browse.mjs a spusťte ho s 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));

Úspěšná 200 odezva obsahuje stránku url, title, extrahovaný content a traceId. Živé procházení může vrátit 202 s retryAfter; počkejte po tuto dobu a pak znovu odešlete stejný požadavek. Kompletní strukturu odpovědi najdete v referenčních informacích k rozhraní API pro procházení.

Troubleshooting

Status Co zkontrolovat
401 Unauthorized Ověřte, že WEBIQ_API_KEY je nastaven a požadavek jej odešle v hlavičce x-apikey.
415 Unsupported Media Type Odeslat content-type: application/json.
429 Too Many Requests Počkejte před opakováním a snižte frekvenci požadavků.
Procházet 404 Not Found Ověřte, že je adresa URL veřejná a platná. Používá se liveCrawl: "fallback" , když indexovaný obsah nemusí být dostupný.
Procházet 202 Accepted Počkejte po vrácenou dobu retryAfter a pak zkuste stejný požadavek zopakovat.

V případě jiných selhání uložte traceId a podívejte se na zpracování chyb nebo se obraťte na podporu Web IQ.

Další kroky

  • Poslední aktualizace v