Schnellstart: Ihre ersten Web IQ-API-Aufrufe ausführen

Führen Sie ihren ersten Microsoft Web IQ REST API-Aufruf in ein paar Minuten aus. Sie durchsuchen das Web, prüfen die Antwort und extrahieren dann Inhalte aus einer bekannten URL.

API-Schlüssel sind die schnellste Möglichkeit, Web IQ auszuwerten. Verwenden Sie für Produktionsworkloads Microsoft Entra ID.

Prerequisites

Tipp

Verwenden Sie den Web IQ Playground, um Anfragen im Browser zu senden und Code in cURL, Python, JavaScript, C#, Java, Go und Ruby zu generieren.

1. API-Schlüssel speichern

Setzen Sie den Schlüssel in eine Umgebungsvariable, damit die Anforderungsbeispiele ihn nicht wiederholen oder ihn in Ihren Quellcode einfügen.

macOS oder Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

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

Warning

Checken Sie Ihren Schlüssel nicht in die Quellcodeverwaltung ein und machen Sie ihn nicht im Browser oder clientseitigen Code verfügbar. Speichern Sie Produktionsanmeldeinformationen in einem Secrets-Manager.

2. Das Web durchsuchen

Verwenden Sie die Websuche, wenn Sie eine Frage oder Abfrage haben und möchten, dass Web IQ relevante Seiten finden und einstufen soll.

Wir empfehlen die Einstellung maxResults = 10, contentFormat = passage und maxLength = 3000 bei jeder Anfrage als optimierten Betriebspunkt. Von dort aus können Sie diese Einstellungen basierend auf Ihrem Anwendungsfall optimieren.

Endpunkt: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

Speichern Sie dieses Beispiel als search.mjs und führen Sie es mit 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. Die Antwort verstehen

Eine erfolgreiche Websuche gibt ein webResults Array zurück. Dieses gekürzte Beispiel zeigt die Felder, die Sie am häufigsten verwenden werden:

{
  "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 und url kennzeichnen die Quelle.
  • content enthält die abfragerelevante Passage, da die Anforderung verwendet wurde contentFormat: "passage".
  • traceId hilft Web IQ Support bei der Untersuchung einer Anfrage.

In REST-Antworten und MCP-Toolergebnissen werden Modellfelder mit null, leerer Zeichenfolge ("") oder leeren Listen-/Arraywerten ([]) weggelassen, einschließlich Feldern geschachtelter Ergebnisobjekte. Behandeln Sie ein nicht vorhandenes Zeichenfolgenfeld als nicht verfügbar und ein nicht vorhandenes Listenfeld als ohne Elemente. Zeichenfolgen, die nur aus Leerraum bestehen, false, 0, leere Wörterbücher, einzelne Array-/Wörterbucheinträge und eingebettete ROH-JSON werden beibehalten. Root-Arrays und Protokollhüllensammlungen wie MCP content sind unverändert.

Siehe die Web Search API-Referenz für alle Parameter und Antwortfelder.

4. Wählen Sie "Websuche" oder "Durchsuchen" aus.

Mit Verwenden Was Sie bekommen
Eine Frage oder Suchabfrage Websuche Bewertete Seiten mit für die Suchanfrage relevantem Inhalt
Eine bestimmte URL Durchsuchen Extrahierte Inhalte dieser Seite

Ein gemeinsamer Grounding-Workflow verwendet beide Endpunkte: Suchen Sie nach relevanten Quellen, wählen Sie eine Ergebnis-URL aus, und durchsuchen Sie diese URL, wenn Sie vollständigeren Seiteninhalt benötigen.

5. Inhalte aus einer URL extrahieren

Verwenden Sie "Durchsuchen", wenn Sie bereits wissen, welche Seite Sie lesen möchten. liveCrawl: "fallback" fordert Web IQ auf, die Seite zu durchforsten, wenn sie noch nicht im Index verfügbar ist.

Endpunkt: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

Speichern Sie dieses Beispiel als browse.mjs und führen Sie es mit 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));

Eine erfolgreiche 200 Antwort enthält die Seite url, title extrahierte content und eine traceId. Eine Live-Durchforstung kann mit retryAfter mit 202 zurückgegeben werden; warten Sie auf diese Dauer, und senden Sie dann die gleiche Anforderung erneut. Informationen zum vollständigen Antwortschema finden Sie in der Browse-API-Referenz.

Troubleshooting

Status Was soll überprüft werden?
401 Unauthorized Bestätigen Sie, dass WEBIQ_API_KEY festgelegt ist und die Anforderung es im Header x-apikey sendet.
415 Unsupported Media Type Senden content-type: application/json.
429 Too Many Requests Warten Sie, bevor Sie es erneut versuchen und die Anforderungshäufigkeit verringern.
Durchsuchen... 404 Not Found Bestätigen Sie, dass die URL öffentlich und gültig ist. Verwenden Sie liveCrawl: "fallback", wenn indizierte Inhalte möglicherweise nicht verfügbar sind.
Durchsuchen... 202 Accepted Warten Sie auf die zurückgegebene retryAfter Wartezeit, und wiederholen Sie dann die gleiche Anfrage.

Speichern Sie bei anderen Fehlern die traceId und siehe Fehlerbehandlung oder wenden Sie sich an den Web IQ-Support.

Nächste Schritte

  • Zuletzt aktualisiert um