Web Search REST API-Referenz

Endpunkt:POST https://api.microsoft.ai/v3/search/web

Beispielanforderung:

curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "latest trends in LLM RAG",
    "maxResults": 10,
    "language": "en",
    "region": "US",
    "maxLength": 3000,
    "contentFormat": "passage"
  }'

Parameters

Parameter Required Typ Vorgabe Description
query Yes string - Eine Suchabfragezeichenfolge. Die maximale Länge beträgt 1000 Zeichen. Unterstützt Operatoren "site:" und "-site:", um Ergebnisse von bestimmten Websites einzuschließen oder auszuschließen (z. B. "Abfrage site:example.com"). Verwenden Sie diese Operatoren nur bei Bedarf, da sie die Ergebnisrelevanz inhärent reduzieren.
maxResults No integer 10 Maximale Anzahl der zurückzugebenden Ergebnisse. Der Standardwert ist 10, und der Maximalwert ist 50.
language No string „de“ Ein 2-Buchstaben-ISO 639-1-Sprachcode für die Schnittstellensprache in den Suchergebnissen. Die vollständige Liste finden Sie unter "Unterstützte Sprachen ".
region No string "US" Ein 2-Buchstaben-Länder-/Regionscode für den Ort, aus dem die Ergebnisse stammen sollen (z. B. "US", "JP", "GB" usw.). Die vollständige Liste finden Sie unter "Unterstützte Regionen ".
location No string - Standortinformationen im Format "lat:<float>; long:<float>", z. B. "lat:40.753250; long:-74.003807". Wenn nicht angegeben, würde der Speicherort in der Abfrage abgeleitet.
contentFormat No string "passage" ("html" mit Volldokumentzugriff) passage gibt die Teile jedes Ergebnisses zurück, die für die Abfrage am relevantesten sind (empfohlen für die Erdung). text, html und geben Sie das vollständige Dokument zurück und markdown gelten nur für Anwendungen mit vollständigem Dokumentzugriff; siehe Passagen und Inhaltsformate. Legen Sie sie für jede Anforderung fest. Hinweis: Die Web-API gibt kein Feld zurück snippet .
Maximale Länge No integer 3000 (10000 mit Volldokumentzugriff) Maximale Anzahl von Zeichen content pro Ergebnis, 1 bis 500000. Ohne vollständigen Dokumentzugriff content beträgt dies höchstens 3000 Zeichen. Siehe "Standardwerte und Grenzwerte". Legen Sie sie für jede Anforderung fest.
safeSearch No string "streng" Ebene der sicheren Suchfilterung. Werte: "off", "strict". Der Standardwert ist "strict".

Inhaltsformate

Legen Sie fest contentFormat = passage , dass die Teile jedes Ergebnisses, die für die Abfrage am relevantesten sind, bis zu maxLength Zeichen (3000 ist ein guter Ausgangspunkt). Es ist das empfohlene Format für die Erdung; siehe Was ist passage, und warum verwenden Sie sie in den häufig gestellten Fragen. Anwendungen mit vollständigem Dokumentzugriff können auch das vollständige Dokument anfordern als text, html oder markdown; für andere Anwendungen geben diese Formate HTTP 403 zurück. Siehe Passagen und Inhaltsformate.

SafeSearch

Mit SafeSearch-Modi können Sie steuern, wie viel vertraulicher Webinhalt die Web-API herausfiltert, bevor Ergebnisse zurückgegeben werden. Vertrauliche Inhalte umfassen Gewalt, Selbstverletzung und andere Kategorien. Der Standardwert ist strict.

Wert Description Empfohlen für
strict Blockiert Inhalte im Zusammenhang mit Erwachsenen-, Rasier-, Gewalt-, Hass- und Selbstverletzungsthemen. Kindersicher, Bildung, Verbraucher-/konservative Bereitstellungen.
off Blockiert weiterhin unzulässige Inhalte. Bei anderen potenziell schädlichen Inhalten wird die Verantwortung für die endgültige Filterung an den Benutzer verschoben. Forschung, Analyse, Opt-In-Unternehmen, erweiterte 3P-Anwendungsfälle.

Note

Wenn Sie den site: Abfrageoperator verwenden, enthält die Antwort möglicherweise erwachsene Inhalte, unabhängig vom safeSearch Wert. Verwenden Sie site: nur, wenn Sie den Inhalt auf der Website kennen und Ihr Szenario die Möglichkeit von erwachsenen Inhalten unterstützt.

Anforderungsheader

Feld Typ Description
host string Host für Microsoft AI-APIs: api.microsoft.ai.
x-apikey oder Autorisierung string Ihr API-Schlüssel oder Entra ID Zugriffstoken für die Authentifizierung.
Inhaltstyp string MIME-Typ des Anforderungstexts. Verwenden Sie application/json.

Antwort

Webantwort

Feld Typ Description
webResults Array von webResult Liste der Webseitenergebnisse.
querySignals querySignals Bewertungssignale auf Abfrageebene für die Suchabfrage.
riskLevel string Die für die Abfrage bewertete Sicherheitsrisikostufe. Mögliche Werte: low, moderate, high, veryHigh.
instrumentationClickBase string Basis-URL zum Klicken auf Pinganforderungen. Fügen Sie einen instrumentationSuffix Wert aus einem Ergebniselement an, um die vollständige Ping-URL zu bilden. Nur für Anwendungen mit dem EnableInstrumentationPing-Profilflagge vorhanden. Hinweis: Benutzerklicks können auch mithilfe der URL-Umleitung protokolliert werden. Wenn die Umleitung aktiviert ist, ist keine Aktion erforderlich, um Benutzerklicks zu protokollieren und instrumentationClickBase nicht in die Antwort eingeschlossen. Anweisungen zum Einrichten finden Sie im Handbuch zur Instrumentierung .
instrumentationCitationBase string Basis-URL für LLM-Protokollpinganforderungen. Fügen Sie eine DATA-Nutzlast an, um die vollständige Ping-URL zu bilden. Nur für Anwendungen mit dem EnableInstrumentationPing-Profilflagge vorhanden.
traceId string Ablaufverfolgungs-ID für das Debuggen.

querySignals

Feld Typ Description
freshness boolean Gibt an, ob neue Dokumente für diese Abfrage priorisiert werden sollen.

webResult

Feld Typ Description
title string Der Titel der Webseite.
url string Die Quell-URL der Webseite. Für China-Benutzer mit aktivierter URL-Umleitung enthält dieses Feld stattdessen dieselbe Umleitungs-URL wie clickUrl.
domain string Der Zielhost für das Ergebnis. Wird nur für China-Benutzer mit aktivierter URL-Umleitung zurückgegeben.
Inhalt string Die detaillierten Inhalte (auch als Grundlage bezeichnet) der Webseite.
crawledAt string Das letzte durchforstete Datum der Webseite folgt ISO8601 Format.
lastUpdatedAt string Das datum der letzten Aktualisierung der Webseite folgt ISO8601 Format.
language string Die Sprache der Webseite verwendet ISO 639-1-Sprachcode.
isAdult boolean Gibt an, ob das Ergebnis erwachsene Inhalte enthält.
clickUrl string Umleitungs-URL, die den Klick durch Bing proxiest. Nur vorhanden, wenn die Klickumleitung aktiviert ist.
instrumentationSuffix string Suffix, das an die URL-Basis der Instrumentierung für dieses Ergebniselement angefügt werden soll. Wird als K-Wert sowohl für die Ping-URL der Instrumentation als auch für die clickUrl Umleitung verwendet. Vorhanden, wenn die Instrumentierungs-Ping aktiviert ist.
contentTier string Die Inhaltsebene des Ergebnisses, die die kommerziellen Zugriffsmerkmale der Inhaltsquelle beschreibt. Mögliche Werte: standard (Standardinhalte, die allen Kunden unter dem Standarddienstangebot zur Verfügung stehen), entitled (Inhalte, die über bestehende Kundenlizenzverträge verfügbar sind, einschließlich Bring Your Own License (BYOL) -Inhalte, die Kunden direkt von Herausgebern lizenziert haben und über ihre eigenen vertraglichen Vereinbarungen zugriffen), premium (Premium-Inhalte, die über das Standardangebot hinausgehen und der Abrechnung unterliegen).

Note

Werte und crawledAtlastUpdatedAt Felder sind optional. Das heißt, ihre Abdeckung ist nicht 100%. Möglicherweise werden leere Werte für diese Felder angezeigt.

Fehlercodes

Statuscode Fehlerkategorie Description Häufige Ursachen
200 Success Die Anfrage war erfolgreich. -
400 Ungültige Anforderung Ungültige Anforderungsparameter. Fehlende erforderliche Felder, ungültige Parameterwerte, falsch formatierter JSON-Code
401 Unauthorized Fehler bei der Authentifizierung oder fehlender Authentifizierung. Ungültiger API-Schlüssel, fehlender x-apikey-Header
403 Verboten Gültige Anmeldeinformationen, aber unzureichende Berechtigungen. API-Schlüssel verfügt nicht über erforderliche Berechtigungen
410 Nicht vorhanden (Gone) HTTPS erforderlich. Anforderung über HTTP anstelle von HTTPS
415 Nicht unterstützter Medientyp Der Inhaltstyp wird nicht unterstützt. Fehlender oder falscher Inhaltstypheader
429 Zu viele Anforderungen Das Ratenlimit wurde überschritten. Zu viele Anforderungen im Zeitfenster
500 Interner Serverfehler Unerwarteter Serverfehler. Temporäres Serverproblem
503 Dienst nicht verfügbar Der Dienst ist vorübergehend nicht verfügbar. Wartung oder vorübergehender Ausfall
504 Gateway-Zeitüberschreitung Zeitüberschreitung bei der Anforderung. Timeout des Upstream-Diensts

Ausführliche Anleitungen zur Fehlerbehandlung finden Sie unter "Fehlerbehandlung".

Siehe auch:Videos Search | News | Search | Images Search | MCP

  • Zuletzt aktualisiert um