Szybki start: wykonywanie pierwszych wywołań interfejsu API Web IQ

Wykonaj pierwsze wywołanie interfejsu API Microsoft Web IQ w ciągu kilku minut. Przeszukasz internet, sprawdzisz odpowiedź, a następnie wyodrębnisz zawartość ze znanego adresu URL.

Jeśli nie masz jeszcze zasobu internetowego IQ, przed kontynuowaniem utwórz go przy użyciu portalu Azure lub Azure CLI.

Wybierz przykład interfejsu API REST lub przykład Python lub zestawu TypeScript SDK poniżej. Zestawy SDK Python i TypeScript obsługują uwierzytelnianie, ponawianie prób i typy odpowiedzi.

Klucze API to najszybszy sposób oceny Web IQ. W przypadku obciążeń produkcyjnych użyj Microsoft Entra ID.

Prerequisites

• Klucz API Web IQ z Profile Management.

Tip

Wolisz rozpocząć pracę z przewodnikiem bez kodowania? Postępuj zgodnie z Rozpocznij pracę w Web IQ Developer Portal: wybierz profil aplikacji, utwórz klucz interfejsu API, wyślij żądanie z Playground, skopiuj wygenerowany kod i sprawdź użycie.

1. Przechowuj swój klucz API

Umieść klucz w zmiennej środowiskowej, aby przykłady żądań go nie powtarzały ani aby nie umieszczać go w kodzie źródłowym.

macOS lub Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Nie commituj klucza do kontroli wersji ani nie udostępniaj go w przeglądarce lub kodzie po stronie klienta. Przechowuj poświadczenia produkcyjne w menedżerze sekretów.

2. Przeszukaj internet

Użyj wyszukiwania w sieci Web, gdy masz pytanie lub zapytanie i chcesz, aby Web IQ znajdował i klasyfikował odpowiednie strony.

Zalecamy ustawienie maxResults = 10, contentFormat = passage i maxLength = 3000 dla każdego żądania jako optymalny punkt pracy. W tym miejscu możesz dostosować te ustawienia w zależności od przypadku użycia.

Punkt końcowy: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 SDK

Zainstaluj zestaw SDK za pomocą pip install webiq (Python 3.11 lub nowszym), a następnie uruchom następujące polecenie:

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)

TypeScript SDK

Zainstaluj zestaw SDK za pomocą npm install @microsoft/webiq (Node.js 22.18 lub nowszego). Zapisz ten przykład jako search.mts i uruchom go za pomocą polecenia 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;
});

Python (REST)

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 (REST)

Zapisz ten przykład jako search.mjs i uruchom go za pomocą polecenia 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. Zrozumienie odpowiedzi

Pomyślne wyszukiwanie w sieci Web zwraca tablicę webResults . W tym skróconym przykładzie pokazano pola, których najczęściej używasz:

{
  "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 i url identyfikują źródło.
• content zawiera fragment odpowiadający zapytaniu, ponieważ w żądaniu użyto contentFormat: "passage".
• traceId pomaga zespołowi pomocy technicznej Web IQ zbadać żądanie.

W przypadku odpowiedzi REST i wyników narzędzia MCP pola modelu z wartościami null lub pustymi ciągami ("") są pomijane, w tym pola zagnieżdżonych obiektów wyników; puste pola listy/tablicy ([]) są przechowywane. Traktuj nieobecne pole tekstowe jako niedostępne i puste pole listy jako bez elementów. Ciągi zawierające wyłącznie białe znaki, false, 0, puste słowniki, poszczególne wpisy tablicy/słownika i osadzone nieprzetworzone dane JSON są zachowywane. Tablice korzeniowe i kolekcje w obwiedni protokołu, takie jak MCP content, są niezmienione.

Zobacz dokumentację interfejsu API wyszukiwania w Sieci Web , aby zapoznać się ze wszystkimi parametrami i polami odpowiedzi.

4. Wybierz pozycję Wyszukiwanie w Sieci Web lub Przeglądaj

Rozpocznij od	Używanie	Co otrzymujesz
Pytanie lub zapytanie wyszukiwania	Wyszukiwanie w Sieci Web	Sklasyfikowane strony z zawartością odpowiednią dla zapytań
Konkretny adres URL	Przeglądaj	Wyodrębniona zawartość z tej strony

Typowy workflow groundingu używa obu punktów końcowych: wyszukiwanie odpowiednich źródeł, wybieranie adresu URL wyniku, a następnie przeglądanie tego adresu URL, gdy potrzebujesz pełniejszej zawartości strony.

5. Wyodrębnianie zawartości z adresu URL

Użyj opcji Przeglądaj, gdy już wiesz, którą stronicę chcesz odczytać. liveCrawl: "fallback" prosi Web IQ o przeszukanie strony, gdy nie jest ona jeszcze dostępna w indeksie. Przeszukiwanie na żywo podlega ograniczeniom wynikającym z zasad grzecznościowych wydawcy i dostępności; fallback nie gwarantuje rzeczywistego przeszukiwania.

Punkt końcowy: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 SDK

Zainstaluj zestaw SDK za pomocą pip install webiq (Python 3.11 lub nowszym), a następnie uruchom następujące polecenie:

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://news.microsoft.com/source/",
        content_format=BrowseContentFormat.markdown,
        max_length=3000,
        live_crawl="fallback",
    )
    print(page.content)

TypeScript SDK

Zainstaluj zestaw SDK za pomocą npm install @microsoft/webiq (Node.js 22.18 lub nowszego). Zapisz ten przykład jako browse.mts i uruchom go za pomocą polecenia node browse.mts.

import { WebIQClient, BrowseContentFormat } from "@microsoft/webiq";

async function main() {
  const client = new WebIQClient({ apiKey: process.env.WEBIQ_API_KEY });

  try {
    const page = await client.browse.fetch(
      "https://news.microsoft.com/source/",
      {
        contentFormat: BrowseContentFormat.MARKDOWN,
        maxLength: 3000,
        liveCrawl: "fallback",
      },
    );
    console.log(JSON.stringify(page, null, 2));
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Python (REST)

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 (REST)

Zapisz ten przykład jako browse.mjs i uruchom go za pomocą polecenia 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));

Pomyślna odpowiedź 200 obejmuje stronę url, title, wyodrębnione content oraz element traceId. Przeszukiwanie na żywo może zwracać 202 z retryAfter, znacznikiem czasu ISO 8601 UTC; poczekaj do tego czasu, a następnie ponownie wyślij to samo żądanie. Zapoznaj się z dokumentacją referencyjną interfejsu Browse API, aby uzyskać pełną specyfikację odpowiedzi.

Troubleshooting

Status	Co należy sprawdzić?
401 Unauthorized	Potwierdź, że WEBIQ_API_KEY jest ustawione, a żądanie wysyła tę wartość w nagłówku x-apikey.
415 Unsupported Media Type	Wyślij content-type: application/json.
429 Too Many Requests	Poczekaj, zanim ponowisz próbę i zmniejsz częstotliwość żądań.
Przeglądaj… 404 Not Found	Upewnij się, że adres URL jest publiczny i prawidłowy. Użyj liveCrawl: "fallback", gdy indeksowana zawartość może być niedostępna.
Przeglądaj… 202 Accepted	Poczekaj do czasu podanego w retryAfter (znacznik czasu UTC w formacie ISO 8601), a następnie ponownie wyślij to samo żądanie.

W przypadku innych niepowodzeń zapisz element traceId i zobacz Obsługa błędów. Aby skontaktować się z pomocą techniczną internetowego IQ, dołącz nazwę firmy, nazwę zasobu internetowego IQ lub profilu aplikacji oraz traceId.

Następne kroki

• Zapoznaj się z dokumentacją interfejsu API wyszukiwania w sieci Web i Browse.
• Użyj zestawów SDK Python i TypeScript.
• Zainstaluj serwer MCP w programie Claude Code, Cursor lub VS Code.
• Skonfiguruj uwierzytelnianie produkcyjne przy użyciu Microsoft Entra ID.
• Uruchom kompletne przykłady z przykładów kodu Web IQ w GitHub.
• Weź udział w module szkoleniowym Zintegruj wiedzę internetową ze swoim agentem za pomocą Web IQ.
• Obejrzyj Uziemianie agentów za pomocą danych ze świata rzeczywistego, odcinek Web IQ z serii Microsoft IQ.