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

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

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

Prerequisites

Tip

Za pomocą Web IQ Playground wysyłaj żądania z przeglądarki i generuj kod w językach cURL, Python, JavaScript, C#, Java, Go i Ruby.

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

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

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 pomocy technicznej Web IQ zbadać żądanie.

W przypadku odpowiedzi REST i wyników narzędzia MCP pola modelu z wartościami "", pustym ciągiem (null) lub pustą listą/tablicą ([]) są pomijane, w tym pola zagnieżdżonych obiektów wyników. Traktuj nieobecne pole ciągu znaków jako niedostępne i nieobecne pole listy jako nieposiadające 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.

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

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

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 zwrócić wartość 202 ze stanem retryAfter; zaczekaj ten czas, 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 czas zwrócony w retryAfter, a następnie spróbuj ponownie wykonać to samo żądanie.

W przypadku innych niepowodzeń zapisz traceId i zobacz Obsługa błędów lub skontaktuj się z Web IQ Support.

Następne kroki

  • Ostatnia aktualizacja o