Referenz zur automatischen REST-API

Note

Auto und Auto Advanced sind in der Regel für jede Web IQ AppID ab dem 17. November 2026 verfügbar. AppIDs ohne vollständigen Dokumentzugriff erhalten Passagen.

Endpunkt:POST https://api.microsoft.ai/v3/auto

Für alle Anforderungen ist ein API-Schlüssel oder Microsoft Entra ID Zugriffstoken erforderlich. Anweisungen zum Einrichten finden Sie unter "Authentifizierung ".

Musteranforderung

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "Microsoft AI announcements",
    "language": "en",
    "region": "US",
    "location": "lat:47.6062;long:-122.3321",
    "mode": "lite",
    "maxResponseLength": 30000,
    "maxCitations": 10,
    "responseFilter": ["web", "news"]
  }'

Beispiel für eine bereichsbezogene Anforderung

Zum Filtern des Web- und Nachrichtenabrufs in auto mithilfe eines benannten Bereichs (siehe Filterergebnisse mit Bereichen), schließen scopeName Sie Folgendes ein und failOnMissingScope:

curl -X POST "https://api.microsoft.ai/v3/auto" \
  -H "x-apikey: <Your API key>" \
  -H "content-type: application/json" \
  -d '{
    "query": "product setup guide",
    "scopeName": "ProductDocs",
    "failOnMissingScope": true,
    "mode": "lite",
    "responseFilter": ["web", "news"]
  }'

Parameters

Parameter Required Typ Vorgabe Description
query Yes string - Suchabfrage, von 1 bis 1.000 Zeichen.
language No string en Zwei-Buchstaben ISO 639-1-Schnittstellensprache.
region No string US Zwei-Buchstaben-Markt- oder Länder-/Regionscode.
mode No string lite lite priorisiert Geschwindigkeit; advanced priorisiert Vollständigkeit.
maxResponseLength No integer 30000 Maximale Inhaltslänge für Webergebnisse, nicht die Gesamtlänge der Antwort. Werte unter 1500 werden auf 1500 geklemmt; Werte über 500000 werden auf 500000 klammert. Bei AppIDs ohne Volldokumentzugriff beträgt der Maximalwert 30000.
maxCitations No integer 10 Maximale Anzahl von Webzitationen, die angefordert werden sollen, von 1 bis 50. Werte unter 1 sind auf 1 geklemmt; Werte über 50 sind auf 50 begrenzt.
location No string - Geografischer Kontext im lat:<latitude>;long:<longitude> Format, z. B lat:47.6062;long:-122.3321. .
responseFilter No Feld von Zeichenfolgen - Berechtigte Antworttypen: web, , news, weathertimezone, images, . videos
includeSites No Feld von Zeichenfolgen - Beschränkt berechtigte Webergebnisse auf diese Websites (Domänen mit optionalen Pfaden), mit höchstens 250 Einträgen. Nachrichten und andere Antworttypen werden nicht gefiltert. Halten Sie die Liste kurz und relevant für optimale Ergebnisse. Pfade unterstützen bis zu zwei Segmente; Tiefere Pfade werden abgeschnitten, also example.com/a/b/c wird behandelt als example.com/a/b.
excludeSites No Feld von Zeichenfolgen - Entfernt Webergebnisse von diesen Websites (Domänen mit optionalen Pfaden), mit höchstens 250 Einträgen und den gleichen Pfadregeln wie includeSites. Wenn eine Website in beiden Listen angezeigt wird, wird sie ausgeschlossen. Nachrichten und andere Antworttypen werden nicht gefiltert.
scopeName No string - Ein benannter Bereich aus der Sammlung, die dem abrechnungskonto der ausgewählten Web IQ AppID zugewiesen ist. Verwenden Sie 1-128 ASCII-Buchstaben, Ziffern, ., oder _-, ohne Leerzeichen. Für "Auto" schränken Bereiche nur Web- und Newsergebnisse ein. Andere Antworttypen werden nicht nach dem Bereich gefiltert und enthalten möglicherweise Ergebnisse außerhalb des Bereichs, auch wenn scopeApplied dies der Zeitpunkt ist true. Ausgelassen oder null bedeutet, dass kein benannter Bereich angefordert wird. Siehe Ergebnisse mit Scopes filtern.
failOnMissingScope No boolean true Steuerelement-Fallback für scopeName; weggelassen oder null mittel true. Wenn der Dienst meldet, dass der Bereich nicht angewendet werden konnte, true gibt HTTP 400 (HandlerInvalidInput) für einen bestätigten fehlenden Bereich oder HTTP 500 (ScopeFailedToApply) für andere Bereichsfehler zurück. false ermöglicht die Suche ohne den Bereich, und scopeApplied: false wenn dieses Ergebnis gemeldet wird. Ein gültiger Bereich wird mit beiden Werten angewendet; Nullabgleichsergebnisse sind kein Bereichsfehler. Hat keine Auswirkung ohne benannten Bereich. Siehe Fehler im Benannten Bereich.

Antwort

Eine erfolgreiche Antwort auf Nachweise gibt zurück 200 OK. Jedes Ergebnis enthält ein typiertes Beweisobjekt und die Zitate, die es unterstützen. Nicht unterstützte oder falsch formatierte Nachweise werden zusammen mit ihren Zitaten weggelassen. Wenn jedes angegebene Nachweisergebnis ausgelassen wird, results ist leer.

AutoEvidenceResponse

Feld Typ Description
results Array von AutoEvidenceResult Nachweiselemente, die mit Zitaten gekoppelt sind, die auf dieses Ergebnis zugeschnitten sind.
querySignals QuerySignals Bewertungssignale auf Abfrageebene für die Suchabfrage.
scopeApplied boolescher Wert (optional) true bedeutet, dass der angeforderte Bereich angewendet wurde, nicht unbedingt seine neueste Definition. false bedeutet, dass der Anwendungsbereich nicht angewendet wurde; failOnMissingScope: false diese nicht bereichslose Antwort zulässt. Wird ausgelassen, wenn der Dienst kein Anwendungsergebnis meldet. Ohne scopeName, wird kein benannter Bereich angefordert. Gehen Sie nicht davon aus, dass das Feld vorhanden oder immer falsevorhanden ist. Beschreibt die aktuelle Anforderung, keine globale Verteilung.
traceId string Korrelations-ID für Debugging und Unterstützung.

QuerySignals

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

AutoEvidenceResult

Feld Typ Description
evidence AutoEvidence Generierte typierte Nachweise.
citations Array von AutoEvidenceCitation Zitate, die nur dieses Beweisergebnis unterstützen.

AutoEvidence

Der eigene type Diskriminator des Beweisobjekts wählt das Schema von content. Verwenden Sie den Nachweistypindex , um die entsprechende Definition zu finden.

Feld Typ Description
type string Diskriminator, der das Nachweisschema identifiziert. Bei Werten wird die Groß-/Kleinschreibung beachtet, z. B structured/timeZone. .
content Zeichenfolge oder Objekt Text oder strukturierte Inhalte, deren Form von type.

AutoEvidenceCitation

Zitatfelder variieren je nach Antworttyp und verfügbaren Quellmetadaten. Nicht jedes Feld ist in jedem Zitat vorhanden.

Feld Typ Description
contentSource string Zitatquelle.
source string Name der zitierten Website.
siteIcon string Symbol-URL für die zitierte Website.
title string Zitattitel.
url string Zitat-URL.
publishedBy string Publisher des zitierten Inhalts.
hostPageUrl string URL der Seite, auf der der zitierte Inhalt gehostet wird.
lastUpdatedAt string Zeitstempel der letzten Aktualisierung.
crawledAt string Durchforstungszeitstempel.
language string Inhaltssprache.
isAdult boolean Gibt an, ob das Zitat erwachsene Inhalte enthält. Wird explizit zurückgegeben, wenn true; behandeln Sie ein ausgelassenes Feld als false.

Antwortspezifische Zitate können auch die folgenden Metadaten enthalten:

Feld Typ Gilt für: Description
observedAt string Weather Beobachtungszeitstempel, der von der Zitatquelle bereitgestellt wird.

Beispielantwort

{
  "results": [
    {
      "evidence": {
        "type": "text",
        "content": "Microsoft announced a new set of AI capabilities."
      },
      "citations": [
        {
          "contentSource": "web",
          "url": "https://www.microsoft.com/en-us/ai",
          "title": "Microsoft AI",
          "language": "en"
        }
      ]
    }
  ],
  "querySignals": { "freshness": true },
  "traceId": "00000000000000000000000000000000"
}

In diesem Beispiel wird nicht angegeben, isAdult sodass Clients es als falsebehandeln sollten.

Nachweistypen

Verwenden Sie diesen Index, um das Schema eines Nachweisobjekts content nachzuschlagen. Antwortkategorien in den Anforderungskategorien responseFilter sind nicht identisch mit Beweisdiskriminatoren in der Antwort: z timezone . B. Anfragen von Zeitzonenantworten, während der zurückgegebene Nachweistyp lautet structured/timeZone.

Antwortkategorie Nachweise type Inhaltsdefinition
web text Textnachweis: Zeichenfolgeninhalt.
news text/news Textnachweis: Zeichenfolgeninhalt mit optionaler Miniaturansicht.
images media/image Bildnachweis: Bildabmessungen, Beschriftung und Miniaturansicht.
videos media/video Videonachweis: Wiedergabemetadaten, Miniaturansichten und optionale Momente.
weather structured/weather Wetterobjekt: Bedingungen, Prognosen, Warnungen und Sonnenlichtdaten.
timezone structured/timeZone Zeitzonenobjekt: Lokale Zeiten, UTC-Offsets und Vergleiche.

Die folgenden Definitionen beschreiben öffentliche Felder. Felder können weggelassen werden, wenn sie nicht verfügbar sind; ein ausgelassenes Feld impliziert keine Nullmaße oder eine leere Antwort. Quellmetadaten und -zuordnungen gehören zu den Zitaten des eingeschlossenen Ergebnisses und nicht zu einem wiederholten Antwortumschlag in jeder Definition.

Beispiele sind illustrative evidence Fragmente, keine vollständigen Antworten. Sehen Sie sich die Beispielantwort für die Eingeschlossene results und citations Struktur an.

Textnachweis

Bei text (Web) und text/news (News content ) handelt es sich nicht um ein Objekt, sondern um eine Zeichenfolge. News-Nachweise können auch eine thumbnail Seite contententhalten.

Feld Typ Description
content string Textnachweis für das Ergebnis.
thumbnail -Objekt (optional) Miniaturansicht der Nachrichten mit url (Zeichenfolge), width (ganze Zahl) und height (ganze Zahl). Abmessungen sind in Pixeln.
{
  "type": "text/news",
  "content": "An example news summary.",
  "thumbnail": {
    "url": "https://example.com/news-thumbnail.jpg",
    "width": 320,
    "height": 180
  }
}

Bildnachweis

Für media/image, content ist ein Bildobjekt. Die Quellbild-URL, die Hostseiten-URL, der Titel und die Quelldaten werden in den Zitaten des Ergebnisses angegeben, wenn verfügbar.

Feld „Inhalt“ Typ Description
caption string Generierte Beschreibung des Bilds.
width integer Bildbreite in Pixel.
height integer Bildhöhe in Pixel.
thumbnailUrl string URL des Miniaturbilds.
lastUpdatedAt string Quelldatum im ISO 8601-Format, sofern verfügbar.
{
  "type": "media/image",
  "content": {
    "caption": "An example city skyline.",
    "width": 1920,
    "height": 1080,
    "thumbnailUrl": "https://example.com/skyline-thumbnail.jpg"
  }
}

Videobeweis

For media/video, content ist ein Videoobjekt. Quelldetails wie Videotitel, URL, Herausgeber und Quelldatum werden in den Zitaten des Ergebnisses angegeben, wenn verfügbar.

Feld „Inhalt“ Typ Description
description string Beschreibung des Videoinhalts.
summary string Kurze Zusammenfassung oder Hervorhebung des Videos.
viewCount integer Anzahl der Videoansichten.
length string Videodauer im HH:MM:SS Format.
allowHttpsEmbedding boolean Gibt an, ob HTTPS-Einbettung zulässig ist.
allowMobileEmbedding boolean Gibt an, ob mobile Einbettungen zulässig sind.
embeddingUrl string URL zum Einbetten des Videos.
thumbnailUrl string Url der Videominiaturansicht.
width integer Videobreite in Pixel.
height integer Videohöhe in Pixel.
lastUpdatedAt string Quelldatum im ISO 8601-Format, sofern verfügbar.
bestMomentIndex integer Index des besten Moments oder Highlights, wenn verfügbar.
moments Array von VideoMoment Videosegmente, sofern verfügbar. Das Array kann leer sein.
{
  "type": "media/video",
  "content": {
    "viewCount": 1200,
    "length": "00:02:30",
    "thumbnailUrl": "https://example.com/video-thumbnail.jpg",
    "moments": []
  }
}

VideoMoment

Feld Typ Description
title string Segmenttitel.
description string Beschreibung des Segments.
startTime string Segmentanfangszeit im d.hh:mm:ss Format.
endTime string Segmentendzeit im d.hh:mm:ss Format.
momentUrl string Direkte URL zum Segment.

Weather-Objekt

Wenn eine Abfrage über das Wetter verfügt, kann Auto ein structured/weather Ergebnis pro Standort zurückgeben. Felder sind enthalten, wenn verfügbar. Lesen Sie numerische Maße zusammen mit units; gehen Sie nicht davon aus, dass ein System mit fester Einheit.

Feld „Inhalt“ Typ Description
location string Ortsname, z. B Seattle, Washington. .
url string Wetterzuordnungs-URL für den Speicherort. Die gleiche URL befindet sich im Zitat des Ergebnisses.
units Objekt Einheitensystem (system) und die Einheiten für temperature, , speed, pressure, distance, heightund time.
alerts Array von WeatherAlert Aktive oder aktuelle Wetterwarnungen für den Standort, gefiltert nach dem Land oder der Region des Benutzers.
currentWeather Objekt Aktuelle Bedingungen, einschließlich condition, , dayPeriod, temperature, universalThermalClimateIndexfeelsLike, humidity, dewPoint, pressureuvLevelwindSpeedvisibilityuvwindDirection, windGust, airQualityusw.observedAt
forecastedWeather Objekt-Array Tägliche Prognosen mit validDate, , condition, temperatureHigh, feelsLikeHightemperatureLow, feelsLikeLow, precipitationChance, Regen und Schneemengen, humidity, , day, nightund almanachourly Prognosen, wenn verfügbar.
sunlight Objekt Sonnenaufgang, Sonnenuntergang, Mondschein, Mondset und Mondphase für ein bestimmtes Datum, wenn die Abfrage nach einem fragt.

Der Aktuelle airQuality kann index, severity, , primaryPollutantund validAt. Eine tägliche Prognose humidity kann enthalten high und low. Seine day und night Unterprognosen können enthalten condition, , precipitationChance, windSpeedund windDirection. Es almanac enthält Sonnen- und Monddaten für validDate.

{
  "type": "structured/weather",
  "content": {
    "location": "Seattle, Washington",
    "units": {
      "system": "Imperial",
      "temperature": "F"
    },
    "currentWeather": {
      "condition": "Cloudy",
      "temperature": 50
    }
  }
}

WeatherAlert

Feld Typ Description
id string Warnungsbezeichner des Anbieters, sofern verfügbar.
name string Name des Wetterereignisses, z. B Frost. .
severity string Schweregrad, z Advisory. B. , Watchoder Warning.
status string Warnungsstatus, z. B Ongoing. .
issuingAuthority string Organisation, die die Warnung ausgegeben hat, z. B National Weather Service. .
url string Link zur ausstellenden Behörde. Enthalten, wenn die Quelle sie bereitstellt.
description string Gefahrenbeschreibung und betroffenes Gebiet.
safetyGuidance string Empfohlene Sicherheitsmaßnahmen, sofern verfügbar.
issuedAt, effectiveAtexpiresAt string Wenn die Warnung ausgegeben wurde, wird wirksam und läuft ab.

Zeitzonenobjekt

Beschreibt structured/timeZonefür , content beschreibt lokale Zeiten oder vergleicht zwei Zeitzonen. Eine Standortsuche kann zurückgegeben werden timeZones; ein Vergleich kann stattdessen zurückgegeben startTimeZonewerden, endTimeZoneund timeDifference. Benötigen Sie nicht alle diese Felder in jeder Antwort.

Feld „Inhalt“ Typ Description
description string Zusammenfassung der für Menschen lesbaren Antwort, falls verfügbar.
timeZones Array von TimeZoneEntry Einträge für eine Antwort auf eine Einzel- oder Mehrere-Ort-Zeit.
startTimeZone TimeZoneEntry Quellzeitzone für einen Vergleich.
endTimeZone TimeZoneEntry Zielzeitzone für einen Vergleich.
timeDifference string Beschreibung der für Menschen lesbaren Zeitdifferenz für einen Vergleich.
{
  "type": "structured/timeZone",
  "content": {
    "timeZones": [
      {
        "timeZoneName": "Pacific Standard Time",
        "timeZoneAbbreviation": "PST",
        "location": "Seattle, Washington",
        "utcOffset": -8,
        "utcTime": "Monday, 2026-11-16T05:00:00Z",
        "localTime": "Sunday, 2026-11-15T21:00:00-08:00"
      }
    ]
  }
}

TimeZoneEntry

Feld Typ Description
timeZoneName string Name der vollständigen Zeitzone.
timeZoneAbbreviation string Abkürzung, z. B PST . oder IST.
location string Ort, Land oder Region, die dem Eintrag zugeordnet ist.
utcOffset Zahl UTC-Offset in Stunden. Kann bruchlos sein, z 5.5. B. ausgelassen, wenn sie nicht verfügbar ist.
utcTime string UTC-Zeit als formatierte Zeichenfolge.
localTime string Ortszeit als formatierte Zeichenfolge.

Zeitzeichenfolgen können ein Präfix für wochentags enthalten; gehen Sie nicht davon aus, dass sie bare ISO 8601-Zeitstempel sind.

Fehlercodes

Statuscode Description
200 Die Anforderung war erfolgreich, einschließlich einer gültigen Suche ohne Ergebnisse.
400 Ungültige Parameter oder falsch formatierte JSON.
401 Fehlende oder ungültige Authentifizierungsanmeldeinformationen.
403 Die authentifizierte Web IQ AppID ist für auto nicht aktiviert.
429 Rate- oder Kontingentgrenze überschritten.
500 Interner Dienstfehler.
503 Ein erforderlicher Dienst ist nicht verfügbar.
504 Zeitüberschreitung der Anforderung.

Informationen zum freigegebenen Fehlerschema und zum Erneuten Wiederholen finden Sie unter "Fehlerbehandlung".