Suchen von Dokumenten (Vorschau-REST-API)

Artikel
06/28/2024

gilt für: 2023-07-01-Preview. Diese Version wird nicht mehr unterstützt. Upgrade sofort auf eine neuere Version.

Wichtig

2023-07-01-Preview fügt Folgendes hinzu:

"Vectors" Abfrageparameter, der alle Vektorabfrageanforderungen angibt. Jedes Objekt sollte die Vektordarstellung der Abfrage, die "k"-Anzahl der nächsten Nachbarn enthalten, die in den Ergebnissen zurückgegeben werden sollen, und die Vektorfelder, die während der Abfrageausführung verwendet werden sollen.

2021-04-30-Preview fügt Folgendes hinzu:

"semanticConfiguration" unterstützt die Bereichsdefinition der semantischen Rangfolge auf bestimmte Felder.
"Captions" Ausdrücke zurück, die aus Schlüsselabschnitten in den höchsten semantischen Dokumenten extrahiert wurden.

2020-06-30-Preview fügt Folgendes hinzu:

"queryType=semantic" unterstützt semantische Reranking und Antworten.
"searchFields"- in einer semantischen Abfrage legt die Prioritätsreihenfolge von Feldern fest, die zum Formulieren von Beschriftungen und Antworten verwendet werden. Dieser Ansatz wurde durch "semanticConfiguration" im Jahr 2021-04-30-Preview ersetzt und ist jetzt veraltet.
"Rechtschreibprüfung" ermöglicht die Rechtschreibkorrektur bei der Abfrageeingabe.
"queryLanguage"- ist für "queryType=semantic" und "speller" erforderlich.
"featuresMode" entpackt eine Suchbewertung, die Berichterstellung für die Häufigkeit pro Feld, die Übereinstimmungsbewertung pro Feld und die Anzahl eindeutiger Übereinstimmungen.

Eine Abfrageanforderung zielt auf die Dokumentensammlung eines einzelnen Indexes in einem Suchdienst ab. Es enthält Parameter, die die Übereinstimmungskriterien definieren, und Parameter, die die Antwort gestalten. Sie können auch einen Indexalias verwenden, um einen bestimmten Index als Ziel zu verwenden, anstatt den Indexnamen selbst zu verwenden.

Sie können GET oder POST für die meisten Abfragen verwenden, aber Sie müssen POST für die Vektorsuche verwenden, da Vektorabfrageparameter nicht in einen URI passen. Abfrageparameter werden in der Abfragezeichenfolge für GET-Anforderungen und im Anforderungstext für POST-Anforderungen angegeben.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Wenn Sie POST verwenden, fügen Sie die "Suche"-Aktion als URI-Parameter hinzu.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Wenn sie mit GET aufgerufen wird, darf die Länge der Anforderungs-URL 8 KB nicht überschreiten. Diese Länge reicht für die meisten Anwendungen aus. Einige Anwendungen erzeugen jedoch große Abfragen, insbesondere wenn OData-Filterausdrücke verwendet werden. Für diese Anwendungen ist HTTP POST eine bessere Wahl, da sie größere Filter als GET zulässt.

Bei POST ist die Anzahl der Klauseln in einem Filter der grenzwertige Faktor, nicht die Größe der unformatierten Filterzeichenfolge, da der Anforderungsgrößengrenzwert für POST ungefähr 16 MB beträgt. Obwohl die GRÖßENbeschränkung für POST-Anforderungen groß ist, können Filterausdrücke nicht beliebig komplex sein. Weitere Informationen zu Einschränkungen der Filterkomplexität finden Sie unter OData-Ausdruckssyntax für Azure AI Search.

URI-Parameter

Parameter	Beschreibung
Dienstname	Erforderlich. Legen Sie diesen Namen auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
Indexname/Docs	Erforderlich. Gibt die Dokumentenauflistung eines benannten Indexes an. Der Name eines Indexalias kann auch anstelle des Indexnamens verwendet werden.
Abfrageparameter	Abfrageparameter werden für den URI für GET-Anforderungen und im Anforderungstext für POST-Anforderungen angegeben.
API-Version	Erforderlich. Weitere Versionen finden Sie unter API-Versionen.

URL-Codierungsempfehlungen

Denken Sie daran, URL-codierten spezifischen Abfrageparametern beim direkten Aufrufen der GET-REST-API zu verwenden. Für einen Suchdokumente Vorgang kann die URL-Codierung für die folgenden Abfrageparameter erforderlich sein:

suchen
$filter
Facette
highlightPreTag
highlightPostTag

Die URL-Codierung wird nur für einzelne Parameter empfohlen. Wenn Sie versehentlich die gesamte Abfragezeichenfolge (alles nach dem ?) codieren, werden Anforderungen abgebrochen.

Außerdem ist die URL-Codierung nur erforderlich, wenn die REST-API direkt mithilfe von GET aufgerufen wird. Es ist keine URL-Codierung erforderlich, wenn SIE POST verwenden oder die Azure AI Search .NET-Clientbibliothekverwenden, die die Codierung für Sie verarbeitet.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben.

Felder	Beschreibung
Inhaltstyp	Erforderlich. Legen Sie diesen Wert auf "application/json" fest.
API-Schlüssel	Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken für die Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Ein API-Schlüssel ist eine eindeutige vom System generierte Zeichenfolge, die die Anforderung an Ihren Suchdienst authentifiziert. Abfrageanforderungen für die Dokumentensammlung können entweder einen Administratorschlüssel oder Abfrageschlüssel als API-Schlüssel angeben. Der Abfrageschlüssel wird für schreibgeschützte Vorgänge für die Dokumentenauflistung verwendet. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung.

Felder

Beschreibung

Inhaltstyp

Erforderlich. Legen Sie diesen Wert auf "application/json" fest.

API-Schlüssel

Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken für die Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Ein API-Schlüssel ist eine eindeutige vom System generierte Zeichenfolge, die die Anforderung an Ihren Suchdienst authentifiziert. Abfrageanforderungen für die Dokumentensammlung können entweder einen Administratorschlüssel oder Abfrageschlüssel als API-Schlüssel angeben. Der Abfrageschlüssel wird für schreibgeschützte Vorgänge für die Dokumentenauflistung verwendet. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung.

Anforderungstext

Für GET: None.

Für POST:

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #,
     "vectors": [
      {
        "value": "a vector representation of the query",
        "k": an integer (number of nearest neighbors to return as top results),
        "fields": "a comma-delimited list of vector fields to use in the query"
      }
     ]
   }

Fortsetzung teilweiser Suchantworten

Manchmal kann Azure AI Search nicht alle angeforderten Ergebnisse in einer einzigen Suchantwort zurückgeben. Eine teilweise Antwort kann aus unterschiedlichen Gründen erfolgen, z. B. wenn die Abfrage zu viele Dokumente zurückgibt, indem sie keine $top angeben oder einen Wert für $top angeben, der zu groß ist. In solchen Fällen enthält Azure AI Search die @odata.nextLink Anmerkung im Antworttext und @search.nextPageParameters, wenn es sich um eine POST-Anforderung handelt. Sie können die Werte dieser Anmerkungen verwenden, um eine andere Suchanforderung zu formulieren, um den nächsten Teil der Suchantwort abzurufen. Dieses Verhalten wird als Fortsetzungs- der ursprünglichen Suchanforderung bezeichnet, und die Anmerkungen werden Fortsetzungstokenaufgerufen. Ausführliche Informationen zur Syntax dieser Anmerkungen und deren Anzeige im Antworttext finden Sie im Beispiel im Abschnitt "Antwort".

Die Gründe, warum Azure AI Search Fortsetzungstoken zurückgeben kann, sind implementierungsspezifisch und können geändert werden. Robuste Clients sollten immer bereit sein, Fälle zu behandeln, in denen weniger Dokumente als erwartet zurückgegeben werden, und ein Fortsetzungstoken ist enthalten, um weiterhin Dokumente abzurufen. Beachten Sie außerdem, dass Sie dieselbe HTTP-Methode wie die ursprüngliche Anforderung verwenden müssen, um den Vorgang fortzusetzen. Wenn Sie beispielsweise eine GET-Anforderung gesendet haben, müssen alle von Ihnen gesendeten Fortsetzungsanforderungen auch GET (und ebenso für POST) verwenden.

Anmerkung

Der Zweck von @odata.nextLink und @search.nextPageParameters besteht darin, den Dienst vor Abfragen zu schützen, die zu viele Ergebnisse anfordern, nicht um einen allgemeinen Mechanismus für die Auslagerung bereitzustellen. Wenn Sie Ergebnisse durchblättern möchten, verwenden Sie $top und $skip zusammen. Wenn Sie z. B. Seiten mit größe 10 wünschen, sollte Ihre erste Anforderung $top=10 und $skip=0 haben, die zweite Anforderung sollte $top=10 und $skip=10 haben, die dritte Anforderung sollte $top=10 und $skip=20 haben usw.

Abfrageparameter

Eine Abfrage akzeptiert mehrere Parameter für die URL, wenn sie mit GET aufgerufen wird, und als JSON-Eigenschaften im Anforderungstext, wenn sie mit POST aufgerufen werden. Die Syntax für einige Parameter unterscheidet sich geringfügig zwischen GET und POST. Diese Unterschiede werden in der folgenden Tabelle aufgeführt.

Name	Art	Beschreibung
Antworten (Vorschau)	Schnur	Wahlfrei. Gültige Werte sind "none" und "extractive". Der Standardwert ist "none". Dieser Parameter ist nur gültig, wenn der Abfragetyp "semantisch" ist. Bei Festlegung auf "extraktiv" formuliert und gibt die Abfrage Antworten von Schlüsselabschnitten in den semantischen Rangfolgen von Dokumenten zurück. Der Standardwert ist eine Antwort, Sie können jedoch bis zu 10 angeben, indem Sie eine Anzahl hinzufügen. Beispielsweise gibt "answers": "extractive\|count-3" drei Antworten zurück. Damit eine Antwort zurückgegeben werden kann, muss der Inhalt des Zielfelds, der wie eine Antwort aussieht, enthalten sein. Die für Antworten verwendeten Sprachmodelle werden geschult, um Antworten zu erkennen und nicht zu generieren. Darüber hinaus muss die Abfrage selbst wie eine Frage aussehen.
API-Version	Schnur	Erforderlich. Version der REST-API, die für die Anforderung verwendet wird. Eine Liste der unterstützten Versionen finden Sie unter API-Versionen. Für diesen Vorgang wird die API-Version als URI-Parameter angegeben, unabhängig davon, ob Sie Search Documents mit GET oder POST aufrufen.
Beschriftungen (Vorschau)	Schnur	Wahlfrei. Gültige Werte sind "none" und "extractive". Der Standardwert ist "none". Dieser Parameter ist nur gültig, wenn der Abfragetyp "semantisch" ist. Wenn sie auf "extractiv" festgelegt ist, gibt die Abfrage Beschriftungen zurück, die aus Schlüsselabschnitten in den höchsten bewerteten Dokumenten extrahiert wurden. Wenn Beschriftungen auf "extraktiv" festgelegt sind, ist die Hervorhebung standardmäßig aktiviert und kann durch Anfügen des Strichs '\|' gefolgt von der Option "Highlight-<true/false>" konfiguriert werden, z. B. "extractive\|highlight-true".
$count	boolesch	Wahlfrei. Gültige Werte sind "true" oder "false". Standardwert ist "false". Wenn dieser Parameter mit POST aufgerufen wird, wird anstelle von $count die Anzahl benannt. Gibt an, ob die Gesamtanzahl der Ergebnisse abgerufen werden soll. Dieser Wert ist die Anzahl aller Dokumente, die den Such- und $filter-Parametern entsprechen, wobei $top und $skip ignoriert werden. Das Festlegen dieses Werts auf "true" kann die Leistung beeinträchtigen. Die Anzahl ist genau, wenn der Index stabil ist, aber alle Dokumente, die aktiv hinzugefügt, aktualisiert oder gelöscht werden, unter oder überschreiben. Wenn Sie nur die Anzahl ohne Dokumente erhalten möchten, können Sie $top=0 verwenden.
Facet oder Facets	Schnur	Wahlfrei. Ein Feld, nach dem das Feld als "facetable" bezeichnet wird. Bei Aufruf mit GET ist `facet` ein Feld (`facet: field1`). Wenn dieser Parameter mit POST aufgerufen wird, wird dieser Parameter anstelle von `facetfacets` benannt und als Array (`facets: [field1, field2, field3]`) angegeben. Die Zeichenfolge kann Parameter enthalten, um das Faceting anzupassen, ausgedrückt als durch Trennzeichen getrennte Namenswertpaare. Gültige Werte sind "count", "sort", "values", "interval" und "timeoffset". "count" ist die maximale Anzahl von Facetbegriffen; Der Standardwert ist 10. Es gibt keine Obergrenze für die Anzahl von Ausdrücken, aber höhere Werte beeinträchtigen die Leistung, insbesondere wenn das faceted-Feld eine große Anzahl eindeutiger Ausdrücke enthält. "facet=category,count:5" ruft z. B. die fünf wichtigsten Kategorien in Facetergebnissen ab. Wenn der Count-Parameter kleiner als die Anzahl eindeutiger Ausdrücke ist, sind die Ergebnisse möglicherweise nicht korrekt. Dies liegt daran, wie Facetingabfragen über Shards verteilt werden. Um eine genaue Anzahl für alle Shards abzurufen, können Sie die Anzahl auf Null oder auf einen Wert festlegen, der größer oder gleich der Anzahl eindeutiger Werte im Facetable-Feld ist. Der Kompromiss ist eine höhere Latenz. "Sortierung" kann auf "count", "-count", "value", "-value" festgelegt werden. Verwenden Sie die Anzahl, um absteigend nach Anzahl zu sortieren. Verwenden Sie -count, um aufsteigend nach Anzahl zu sortieren. Verwenden Sie den Wert, um aufsteigend nach Wert zu sortieren. Verwenden Sie -value, um absteigend nach Wert zu sortieren (z. B. "facet=category,count:3,sort:count", ruft die drei obersten Kategorien im Facet absteigend nach der Anzahl der Dokumente mit jedem Ortsnamen ab. Wenn die drei wichtigsten Kategorien Budget, Motel und Luxus sind und Budget fünf Treffer hat, Hat Motel sechs, und Luxus hat vier, dann sind die Buckets in der Reihenfolge Hotel, Budget, Luxus. Bei -value erzeugt "facet=rating,sort:-value" Buckets für alle möglichen Bewertungen in absteigender Reihenfolge nach Wert (z. B. wenn die Bewertungen zwischen 1 und 5 liegen, werden die Buckets 5, 4, 3, 2, 1 sortiert, unabhängig davon, wie viele Dokumente mit den einzelnen Bewertungen übereinstimmen). "Values" kann auf numerische Oder Edm.DateTimeOffset-Werte festgelegt werden, die einen dynamischen Satz von Faceteingabewerten angeben (z. B. "facet=baseRate,values:10 \| 20" erzeugt drei Buckets: eine für den Basissatz 0 bis einschließlich 10, eine für 10 bis einschließlich 20 und eine für 20 und höher). Eine Zeichenfolge "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" erzeugt zwei Buckets: eine für Hotels, die vor Februar 2010 renoviert wurden, und eine für Hotels, die am 1. Februar 2010 oder höher renoviert wurden. Die Werte müssen in sequenzieller aufsteigender Reihenfolge aufgelistet werden, um die erwarteten Ergebnisse zu erhalten. "Intervall" ist ein ganzzahliges Intervall, das größer als 0 für Zahlen oder Minute, Stunde, Tag, Woche, Monat, Quartal, Jahr für Datumszeitwerte ist. Beispielsweise erzeugt "facet=baseRate,interval:100" Buckets basierend auf Basisratenbereichen der Größe 100. Wenn Basissätze alle zwischen 60 $ und 600 $ liegen, gibt es Buckets für 0-100, 100-200, 200-300, 300-400, 400-500 und 500-600. Die Zeichenfolge "facet=lastRenovationDate,interval:year" erzeugt jedes Jahr einen Bucket, als Hotels renoviert wurden. "Timeoffset" kann auf ([+-]hh:mm, [+-]hhmm oder [+-]hh) festgelegt werden. Bei Verwendung muss der Timeoffset-Parameter mit der Intervalloption kombiniert werden, und nur, wenn er auf ein Feld vom Typ Edm.DateTimeOffset angewendet wird. Der Wert gibt den UTC-Zeitversatz an, der bei der Festlegung von Zeitgrenzen berücksichtigt werden soll. Beispiel: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" verwendet die Tagesgrenze, die um 01:00:00 UTC beginnt (Mitternacht in der Zielzeitzone). Anzahl und Sortierung kann in derselben Facetspezifikation kombiniert werden, sie können jedoch nicht mit Intervallen oder Werten kombiniert werden, und Intervalle und Werte können nicht kombiniert werden. Intervall-Facets für Datumszeit werden basierend auf der UTC-Zeit berechnet, wenn kein Zeitoffset angegeben ist. Beispiel: Für "facet=lastRenovationDate,interval:day" beginnt die Tagesgrenze um 00:00:00 UTC.
featuresMode (Vorschau)	boolesch	Wahlfrei. Gültige Werte sind "enabled" und "disabled". Der Standardwert ist "disabled". Ein Wert, der angibt, ob die Ergebnisse Abfrageergebnisfeaturesenthalten sollen. Wird verwendet, um die Relevanzbewertung eines Dokuments in Bezug auf die Abfrage zu berechnen, z. B. pro Feldähnlichkeit. Verwenden Sie "enabled", um weitere Abfrageergebnisfeatures verfügbar zu machen: pro Feldgleichheitsbewertung, häufigkeit des Feldausdrucks und pro Feldanzahl eindeutiger Token. Weitere Informationen finden Sie unter Ähnlichkeit und Bewertung.
$filter	Schnur	Wahlfrei. Ein strukturierter Suchausdruck in der OData-Standardsyntax. Nur filterbare Felder können in einem Filter verwendet werden. Wenn dieser Parameter mit POST aufgerufen wird, wird dieser Parameter anstelle von $filter benannt. Details zur Teilmenge der OData-Ausdrucksgrammatik, die von Azure AI Search unterstützt wird, finden Sie unter OData-Ausdruckssyntax für Azure AI Search.
Höhepunkt	Schnur	Wahlfrei. Eine Gruppe von durch Trennzeichen getrennten Feldnamen, die für Trefferhighlights verwendet werden. Nur durchsuchbare Felder können zum Hervorheben von Treffern verwendet werden. Standardmäßig gibt Azure AI Search bis zu fünf Hervorhebungen pro Feld zurück. Der Grenzwert kann pro Feld konfiguriert werden, indem "-<max# der Hervorhebungen>" nach dem Feldnamen angefügt wird. Beispielsweise gibt "highlight=title-3,description-10" bis zu drei hervorgehobene Treffer aus dem Titelfeld und bis zu 10 Treffer aus dem Beschreibungsfeld zurück. Die maximale Anzahl von Hervorhebungen muss eine ganze Zahl zwischen 1 und 1000 (einschließlich) sein.
highlightPostTag	Schnur	Wahlfrei. Standardmäßig wird `"</em>"`. Ein Zeichenfolgentag, das an den hervorgehobenen Ausdruck angefügt wird. Muss mit highlightPreTag festgelegt werden. Reservierte Zeichen in der URL müssen prozentcodiert sein (z. B. %23 anstelle von "#").
highlightPreTag	Schnur	Wahlfrei. Standardmäßig wird `"</em>"`. Ein Zeichenfolgentag, das dem hervorgehobenen Ausdruck vorangestellt wird. Muss mit highlightPostTag festgelegt werden. Reservierte Zeichen in der URL müssen prozentcodiert sein (z. B. %23 anstelle von "#").
minimumCoverage	ganze Zahl	Wahlfrei. Gültige Werte sind eine Zahl zwischen 0 und 100, die den Prozentsatz des Indexes angibt, der für den Dienst der Abfrage verfügbar sein muss, bevor sie als Erfolg gemeldet werden kann. Standardwert ist "100". Eine hundertprozentige Abdeckung bedeutet, dass alle Shards auf die Anforderung geantwortet haben (weder Dienststatusprobleme noch Wartungsaktivitäten verringerte Abdeckung). Unter der Standardeinstellung gibt weniger als die vollständige Abdeckung DEN HTTP-Statuscode 503 zurück. Lowering minimumCoverage kann nützlich sein, wenn 503 Fehler auftreten und Sie die Wahrscheinlichkeit des Abfrageerfolgs erhöhen möchten, insbesondere für Dienste, die für ein Replikat konfiguriert sind. Wenn Sie "minimumCoverage" festlegen und die Suche erfolgreich verläuft, wird HTTP 200 zurückgegeben und ein @search.coverage Wert in die Antwort eingeschlossen, der den Prozentsatz des Indexes angibt, der in der Abfrage enthalten war. In diesem Szenario werden nicht alle übereinstimmenden Dokumente in den Suchergebnissen vorhanden sein, aber wenn die Suchverfügbarkeit wichtiger ist, als zurückrufen, kann die Verringerung der Abdeckung eine lebensfähige Entschärfungsstrategie sein.
$orderby	Schnur	Wahlfrei. Eine Liste von kommagetrennten Ausdrücken zum Sortieren der Ergebnisse nach. Wenn dieser Parameter mit POST aufgerufen wird, wird dieser Parameter anstelle von $orderby benannt. Jeder Ausdruck kann entweder ein Feldname oder ein Aufruf der Geo.distance()-Funktion sein. Auf jeden Ausdruck kann "asc" folgen, um aufsteigend und "desc" anzugeben, um absteigend anzugeben. Wenn im Sortierfeld Nullwerte vorhanden sind, werden NULL-Werte zuerst in aufsteigender Reihenfolge und zuletzt in absteigender Reihenfolge angezeigt. Der Standardwert ist die aufsteigende Reihenfolge. Die Verknüpfungen werden durch die Übereinstimmungsergebnisse von Dokumenten unterbrochen. Wenn keine $orderby angegeben ist, wird die Standardsortierreihenfolge nach Dokumentabgleichsbewertung absteigend ausgeführt. Es gibt eine Beschränkung von 32 Klauseln für $orderby.
queryLanguage (Vorschau)	Schnur	Wahlfrei. Gültige Werte sind eine unterstützte Sprache. Standardmäßig wird "en-us" verwendet. Dieser Parameter muss festgelegt werden, wenn Sie entweder speller=lexicon oder queryType=semantic verwenden. Die in "queryLanguage" angegebene Sprache wird sowohl für die Rechtschreibprüfung als auch für die semantischen Modelle verwendet, die Ergebnisse reranken und eine Beschriftung oder Antwort extrahieren. Die für "queryLanguage" verwendeten Bibliotheken sind unabhängig von anderen gebietsschemabasierten Feldattributen, z. B. Sprachanalyse, die für die Indizierung und die Volltextsuche verwendet werden.
queryType	Schnur	Wahlfrei. Gültige Werte sind "simple", "full" oder "semantic" (Vorschau). Der Standardwert ist "einfach". Dieser Wert wird für die Vektorsuche ignoriert, gilt jedoch für die Textsuche in Hybridszenarien. "simple" interpretiert Abfragezeichenfolgen mithilfe der einfachen Abfragesyntax, die Symbole wie `+`, ``und `""`ermöglicht. Abfragen werden standardmäßig in allen durchsuchbaren Feldern (oder in searchFields angegebenen Feldern) in jedem Dokument ausgewertet. "vollständig" interpretiert Abfragezeichenfolgen mithilfe der vollständigen Lucene-Abfragesyntax, die feldspezifische und gewichtete Suchvorgänge zulässt. Die Bereichssuche in der Lucene-Abfragesprache wird nicht zugunsten von $filter unterstützt, die ähnliche Funktionen bietet. "Semantik" verbessert die Genauigkeit von Suchergebnissen, indem die top 50 Übereinstimmungen mithilfe eines Bewertungsmodells, das auf dem Bing-Korpus trainiert wurde, für Abfragen in natürlicher Sprache im Gegensatz zu Schlüsselwörtern neu ranken. Wenn Sie den Abfragetyp auf Semantik festlegen, müssen Sie auch "queryLanguage" und "semanticConfiguration" festlegen. Sie können optional Antworten festlegen, wenn Sie auch die wichtigsten 3 Antworten zurückgeben möchten, wenn die Abfrageeingabe in natürlicher Sprache formuliert wurde ("Was ist ein ...*), und Sie können optional Beschriftungen festlegen, um Wichtige Passagen aus den höchsten bewerteten Dokumenten zu extrahieren.
scoringParameter	Schnur	Wahlfrei. Gibt die Werte für jeden Parameter an, der in einer Bewertungsfunktion definiert ist (z. B. referencePointParameter) mit dem Format "name-value1,value2,..." Wenn dieser Parameter mit POST aufgerufen wird, heißt dieser Parameter "scoringParameters" anstelle von "scoringParameter". Außerdem geben Sie es als JSON-Array von Zeichenfolgen an, wobei jede Zeichenfolge ein separates Name-Werte-Paar ist. Für Bewertungsprofile, die eine Funktion enthalten, trennen Sie die Funktion von der Eingabeliste durch ein `-` Zeichen. Beispielsweise wäre eine Funktion namens `"mylocation"` "&scoreParameter=mylocation--122,2,44,8". Der erste Strich trennt den Funktionsnamen von der Wertliste, während der zweite Strich Teil des ersten Werts ist (Längengrad in diesem Beispiel). Bei Bewertungsparametern, z. B. zum Erhöhen von Tags, die Kommas enthalten können, können Sie beliebige werte in der Liste mit einfachen Anführungszeichen escapen. Wenn die Werte selbst einfache Anführungszeichen enthalten, können Sie sie durch Verdoppelung escapen. Angenommen, Sie haben einen Tag-Boostparameter namens `"mytag"` und möchten die Tagwerte "Hello, O'Brien" und "Smith" erhöhen, die Abfragezeichenfolgenoption wäre dann "&scoringParameter=mytag-'Hello, O'Brien',Smith". Anführungszeichen sind nur für Werte erforderlich, die Kommas enthalten.
scoringProfile	Schnur	Wahlfrei. Der Name eines Bewertungsprofils, um Übereinstimmungsergebnisse für übereinstimmende Dokumente auszuwerten, um die Ergebnisse zu sortieren.
scoreStatistics	Schnur	Wahlfrei. Gültige Werte sind "local" oder "global". Der Standardwert ist "local". Geben Sie an, ob Bewertungsstatistiken, z. B. Dokumenthäufigkeit, global (über alle Shards hinweg) für eine konsistentere Bewertung oder lokal (auf dem aktuellen Shard) für niedrigere Latenz berechnet werden sollen. Siehe Bewertungsstatistiken in Azure AI Search. Bewertungsstatistiken werden immer lokal für Ausdrücke berechnet, die fuzzy search ('~')verwenden.
suchen	Schnur	Wahlfrei. Der text, nach dem gesucht werden soll. Dieser Wert wird für die Vektorsuche ignoriert, gilt jedoch für die Textsuche in Hybridszenarien. In REST-APIs werden alle durchsuchbaren Felder standardmäßig durchsucht, es sei denn, searchFields ist angegeben. Im Index wird Text in einem durchsuchbaren Feld tokenisiert, sodass mehrere Ausdrücke durch Leerzeichen getrennt werden können (z. B. "search=hello world"). Verwenden Sie ``, um einem beliebigen Ausdruck zu entsprechen (dies kann für boolesche Filterabfragen nützlich sein). Das Auslassen dieses Parameters hat den gleichen Effekt wie das Festlegen auf ``. Einzelheiten zur Suchsyntax finden Sie unter einfache Abfragesyntax. Ergebnisse können manchmal beim Abfragen über durchsuchbare Felder überraschend sein. Der Tokenizer enthält Logik zum Behandeln von Fällen, die für englischen Text wie Apostrophe, Kommas in Zahlen usw. üblich sind. Beispielsweise entspricht "search=123.456" einem einzelnen Begriff "123.456" anstelle der einzelnen Begriffe "123" und "456", da Kommas als Tausendertrennzeichen für große Zahlen in Englisch verwendet werden. Aus diesem Grund wird empfohlen, Leerzeichen anstelle von Interpunktion zu verwenden, um Ausdrücke im Suchparameter zu trennen.
searchMode	Schnur	Wahlfrei. Gültige Werte sind "any" oder "all" Defaults to "any". Gibt an, ob eine oder alle Suchbegriffe übereinstimmen müssen, um das Dokument als Übereinstimmung zu zählen.
searchFields	Schnur	Wahlfrei. Die Liste der durch Kommas getrennten Feldnamen, die nach dem angegebenen Text gesucht werden sollen. Zielfelder müssen im Indexschema als durchsuchbar gekennzeichnet sein und müssen vom Typ `Edm.String`, `Edm.ComplexType`oder `Collection(Edm.String)`sein.
$select	Schnur	Wahlfrei. Eine Liste von durch Trennzeichen getrennten Feldern, die in das Resultset aufgenommen werden sollen. Nur felder, die als abrufbar gekennzeichnet sind, können in diese Klausel aufgenommen werden. Wenn nicht angegeben oder auf `*`festgelegt ist, werden alle felder, die im Schema als abrufbar gekennzeichnet sind, in die Projektion einbezogen. Wenn dieser Parameter mit POST aufgerufen wird, wird der Parameter anstelle von $select ausgewählt.
semanticConfiguration (Vorschau)	Schnur	Wahlfrei. Erforderlich, wenn queryType="semantic". Der Name der semantischen Konfiguration, die auflistet, welche Felder für semantische Rangfolge, Beschriftungen, Hervorhebungen und Antworten verwendet werden sollen. Weitere Informationen finden Sie unter Erstellen einer semantischen Abfrage.
sessionId	Schnur	Wahlfrei. Die Verwendung von sessionId trägt dazu bei, die Relevanzbewertungskonsistenz für Suchdienste mit mehreren Replikaten zu verbessern. Bei Konfigurationen mit mehreren Replikaten kann es geringfügige Unterschiede zwischen Relevanzbewertungen einzelner Dokumente für dieselbe Abfrage geben. Wenn eine Sitzungs-ID bereitgestellt wird, bemüht sich der Dienst am besten, eine bestimmte Anforderung an dasselbe Replikat für diese Sitzung weiterzuleiten. Seien Sie vorsichtig, dass die Wiederverwendung der gleichen Sitzungs-ID-Werte wiederholt den Lastenausgleich der Anforderungen über Replikate hinweg beeinträchtigen und die Leistung des Suchdiensts beeinträchtigen kann. Der als sessionId verwendete Wert kann nicht mit einem '_'-Zeichen beginnen. Wenn ein Dienst über keine Replikate verfügt, hat dieser Parameter keine Auswirkungen auf die Leistung oder die Konsistenz der Bewertung.
$skip	ganze Zahl	Wahlfrei. Die Anzahl der zu überspringenden Suchergebnisse. Wenn dieser Parameter mit POST aufgerufen wird, wird dieser Parameter anstelle von $skip benannt. Dieser Wert darf nicht größer als 100.000 sein. Wenn Sie Dokumente sequenziieren müssen, aber aufgrund dieser Einschränkung nicht $skip verwenden können, sollten Sie $orderby für ein Feld verwenden, das eindeutige Werte für jedes Dokument im Index enthält (z. B. den Dokumentschlüssel), und $filter stattdessen mit einer Bereichsabfrage.
Rechtschreibprüfung (Vorschau)	Schnur	Wahlfrei. Gültige Werte sind "none" und "lexicon". Der Standardwert ist "none". Verbessern Sie den Rückruf durch Rechtschreibkorrektur einzelner Suchabfragebegriffe. Sie können sie für einfache, vollständige und semantische Abfragetypen verwenden. Bei Verwendung erfordert der Rechtschreibparameter "queryLanguage". Weitere Informationen und Beispiele finden Sie unter Hinzufügen der Rechtschreibprüfung zu Abfragen.
$top	ganze Zahl	Wahlfrei. Die Anzahl der abzurufenden Suchergebnisse. Dieser Standardwert ist 50. Wenn dieser Parameter mit POST aufgerufen wird, wird dieser Parameter anstelle von $top oben benannt. Wenn Sie einen Wert angeben, der größer als 1000 ist und mehr als 1000 Ergebnisse vorliegen, werden nur die ersten 1000 Ergebnisse zurückgegeben, zusammen mit einem Link zur nächsten Ergebnisseite (siehe "@odata.nextLink" im folgenden Beispiel). Azure AI Search verwendet serverseitige Paging-, um zu verhindern, dass Abfragen zu viele Dokumente gleichzeitig abrufen. Die Standardseitengröße beträgt 50, während die maximale Seitengröße 1000 beträgt. Dies bedeutet, dass standardmäßig Suchdokumente höchstens 50 Ergebnisse zurückgibt, wenn Sie keine $top angeben. Wenn mehr als 50 Ergebnisse vorliegen, enthält die Antwort Informationen zum Abrufen der nächsten Seite mit höchstens 50 Ergebnissen (siehe "@odata.nextLink" und "@search.nextPageParameters" in den Examples unten. Wenn Sie einen Wert größer als 1000 für $top angeben und mehr als 1000 Ergebnisse enthalten, werden nur die ersten 1000 Ergebnisse zurückgegeben, zusammen mit Informationen zum Abrufen der nächsten Seite mit höchstens 1000 Ergebnissen.
Vektoren (Vorschau)	Anordnung	Wahlfrei. Der Objekttyp innerhalb des Arrays ist eine Vektorabfrage. Die Abfrageparameter für Vektorabfragen. "Value" ist die Vektordarstellung einer Suchabfrage. Diese Darstellung muss extern gebildet werden. Azure AI Search erstellt keine Einbettungen. "k" ist eine ganze Zahl, die die Anzahl der nächsten Nachbarn angibt, die als Toptreffer zurückgegeben werden sollen. Der Standardwert ist 50. Der Mindestwert beträgt 1 und maximal 10.000. "Felder" ist ein durch Trennzeichen getrennte Listenfeldnamen, die Vektordaten enthalten. Nur Felder vom Typ `Collection(Edm.Single)` können in die Liste "Felder" aufgenommen werden.

Antwort

Statuscode: 200 OK wird für eine erfolgreiche Antwort zurückgegeben. In diesem Artikel gibt es zwei Beispielantworten, jeweils eine für die semantische Suche und featuresMode.

Beispielantwort für semantische Abfrage

Das erste Beispiel zeigt die vollständige Antwort für das oberste Ergebnis für die semantische Abfrage "How do clouds form".

"@search.answers" wird angezeigt, wenn Sie den Antwortparameter angeben, und wenn die Abfrage und die zielbezogenen Felder im Index Inhalte enthalten, die als Antwort erkannt werden können. Das @search.answers Array, das einen Schlüssel, Text und Hervorhebungen enthält. Die Bewertung ist ein Indikator für die Stärke der Antwort.
"value" ist der Textkörper der Antwort. Der @search.rerankerScore wird vom semantischen Bewertungsalgorithmus zugewiesen und wird verwendet, um Ergebnisse zu bewerten (@search.score stammt aus dem BM25-Ähnlichkeitsalgorithmus, der beim Bewerten der ersten Ergebnisse verwendet wird). Beschriftungen umfassen Nur-Text und hervorgehobene Versionen. Dieses Beispiel wurde mit OCR- und Entitätserkennungskompetenzen erstellt. Felder für den extrahierten und zusammengeführten Inhalt sind in der Antwort enthalten.

{
    "@search.answers": [
        {
            "key": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQ1LnBkZg2",
            "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
            "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
            "score": 0.94639826
        }
    ],
    "value": [
        {
            "@search.score": 0.5479723,
            "@search.rerankerScore": 1.0321671911515296,
            "@search.captions": [
                {
                    "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
                    "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
                }
            ],
            "content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "metadata_storage_path": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQxLnBkZg2",
            "people": [],
            "locations": [
                "Pacific Northwest",
                "North America",
                "Vancouver"
            ],
            "merged_content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "text": [],
            "layoutText": []
        }
    ]
}

Beispielantwort für featuresMode

This example shows "@search.features" output from a query that includes featuresMode.

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "featuresMode" : ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Beispiele

Weitere Beispiele finden Sie in OData-Ausdruckssyntax für Azure AI Search.

Beispiel: einfache Suche

Suchen Sie Dokumente im Index mithilfe einer einfachen Abfragesyntax. Diese Abfrage gibt Hotels zurück, in denen durchsuchbare Felder die Begriffe "Komfort" und "Ort" enthalten, aber nicht "motel":

Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }

Trinkgeld

Die Verwendung von searchMode=all setzt den Standardwert von searchMode=anyaußer Kraft, um sicherzustellen, dass -motel "UND NICHT" anstelle von "ODER NICHT" bedeutet. Ohne searchMode=allerhalten Sie "OR NOT", die erweitert wird, anstatt Suchergebnisse einzuschränken, und dies kann für einige Benutzer kontra intuitiv sein.

Beispiel: vollständige Lucene-Suche

Suchen Sie Dokumente im Index mithilfe der Lucene-Abfragesyntax (siehe Lucene-Abfragesyntax in Azure AI Search). Diese Abfrage gibt Hotels zurück, in denen das Kategoriefeld den Begriff "Budget" und alle durchsuchbaren Felder enthält, die den Ausdruck "kürzlich renoviert" enthalten. Dokumente, die den Ausdruck "kürzlich renoviert" enthalten, werden aufgrund des Ausdrucks boost value (3) höher eingestuft.

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2021-04-30-Preview&querytype=full`

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

Beispiel: semantische Suche

Rufen Sie das semantische Bewertungsmodell mit Antworten, Beschriftungen und hervorgehobenen Inhalten auf. Die Antwort für diese Abfrage finden Sie im vorherigen Abschnitt.

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
{
  "search": "how do clouds form",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "queryLanguage": "en-us",
  "answers": "extractive",
  "captions": "extractive",
  "count": "true"
}

Beispiel: Vektorsuche

Für einen Index mit Feldern vom Typ Collection(Edm.Single) und einer Vektorkonfiguration können Sie Vektorabfrageparameter angeben. Zu den Vektorabfrageparametern gehören die Vektorfelder, die im Gültigkeitsbereich der Abfrage enthalten sind, die Anzahl der wichtigsten Treffer, die zurückgegeben werden sollen, und eine Vektordarstellung der Abfrageeingabe.

Das Hinzufügen eines "select"-Parameters ist hilfreich, wenn der Index Textfelder enthält. Der Abgleich und die Relevanz basieren auf Vektoren, aber Felder mit lesbaren Inhalten sind nützlicher für jemanden, der die Ergebnisse liest. Alternativ können Sie Code schreiben, der die Vektordaten in Ihren Suchergebnissen in Text konvertiert.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search": (this parameter is ignored in vector search),
    "vectors": [{
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    }],
    "select": "title, content, category"
}

Beispiel: orderby

Durchsuchen Sie den Index, und geben Sie ergebnisse nach Datum in absteigender Reihenfolge zurück.

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Beispiel: Filtern mithilfe eines OData-Ausdrucks

Abrufen von Dokumenten, die einem bestimmten Filterausdruck entsprechen:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Beispiel: faceted search

Durchsuchen Sie in einer facetierten Suche den Index, und rufen Sie Facets nach Kategorien, Bewertungen, Tags sowie Elementen mit BaseRate in bestimmten Bereichen ab.

GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }

Beachten Sie, dass sich das letzte Facet auf einem Unterfeld befindet. Facets zählen das übergeordnete Dokument (Hotels) und nicht zwischengeschaltete Filialdokumente (Räume), sodass die Antwort die Anzahl der Hotels bestimmt, die über Zimmer in jedem Preis-Bucket verfügen.

Beispiel: Eingrenzen einer Faceted-Abfrage

Mit einem Filter können Sie das vorherige Faceted-Abfrageergebnis einschränken, nachdem der Benutzer "Bewertung 3" und die Kategorie "Motel" ausgewählt hat.

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview 
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Beispiel: faceted search with limits on each category

Legen Sie in einer Faceted Search eine Obergrenze für eindeutige Ausdrücke fest, die in einer Abfrage zurückgegeben werden. Der Standardwert ist 10, Sie können diesen Wert jedoch mithilfe des Count-Parameters für das Facet-Attribut erhöhen oder verkleinern. In diesem Beispiel werden Facets für die Stadt zurückgegeben, die auf 5 beschränkt sind.

GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }

Beispiel: In-Field Search-

Durchsuchen des Indexes innerhalb bestimmter Felder (z. B. eines Sprachfelds)

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Durchsuchen Sie den Index über mehrere Felder. Sie können z. B. durchsuchbare Felder in mehreren Sprachen speichern und abfragen, alle innerhalb desselben Indexes. Wenn englische und französische Beschreibungen im selben Dokument vorhanden sind, können Sie beliebige oder alle in den Abfrageergebnissen zurückgeben:

GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }

Sie können jeweils nur einen Index abfragen. Erstellen Sie nicht mehrere Indizes für jede Sprache, es sei denn, Sie möchten jeweils eine Abfrage durchführen.

Beispiel: Auslagerungsergebnisse

Abrufen der ersten Seite von Elementen (Seitengröße ist 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Abrufen der zweiten Seite von Elementen (Seitengröße ist 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Beispiel: Einschränken von Feldern in einem Resultset-

Abrufen einer bestimmten Gruppe von Feldern:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Beispiel: Treffermarkierung in Ergebnissen

Durchsuchen Sie den Index, und geben Sie Fragmente mit Trefferhighlights zurück:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Beispiel: Geospatialsuche

Durchsuchen Sie den Index, und geben Sie Dokumente zurück, die von näher bis weiter entfernt von einem Referenzspeicherort sortiert sind:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Beispiel: "Von mir suchen" (Relevanz von nahe gelegenen Standorten

Durchsuchen Sie den Index, vorausgesetzt, es gibt ein Bewertungsprofil namens "Geo" mit zwei Entfernungsbewertungsfunktionen, eine, die einen Parameter namens "currentLocation" definiert und einen Parameter namens "lastLocation" definiert. Im folgenden Beispiel weist "currentLocation" ein Trennzeichen eines einzelnen Gedankenstrichs (-) auf. Gefolgt von Längen- und Breitengradkoordinaten, wobei Längengrad ein negativer Wert ist.

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

Beispiel: Abfrage über voller Index anstelle von Shards

Suchen Sie Dokumente im Index, während Sie eine konsistente Bewertung gegenüber geringerer Latenz bevorzugen. Diese Abfrage berechnet Dokumentfrequenzen über den gesamten Index hinweg und bemüht sich am besten, dasselbe Replikat für alle Abfragen innerhalb derselben "Sitzung" zu adressieren, wodurch eine stabile und reproduzierbare Rangfolge generiert wird.

GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }

Beispiel: Bewertungsstatistik (featuresMode)

Suchen Sie Dokumente im Index, und geben Sie eine Liste der Informationsempfangsfeatures für jedes Ergebnis zurück, das die Bewertung zwischen dem übereinstimmenden Dokument und der Abfrage beschreibt. Die Abfrage berechnet auch Dokumentfrequenzen über den gesamten Index hinweg, um eine konsistentere Bewertung zu erzielen.

GET /indexes/hotels/docs?search=hotel&featuresMode=enabled&scoringStatistics=global&api-version=2021-04-30-Preview

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "featuresMode": "enabled",
      "scoringStatistics" :"global"
    }

Ein Beispiel für eine Antwort, die search.features enthält, sieht ähnlich wie folgt aus:

    "@search.score": 0.91875637,
    "@search.features": {
        "Description": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.2917966,
            "termFrequency": 2
        },
        "HotelName": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.44458693,
            "termFrequency": 1
        }
      . . .

Definitionen

Dieser Abschnitt enthält Details zu Parametern, die zu komplex sind, um sie in der Haupttabelle abzudecken.

Verbinden	Beschreibung
queryLanguage-	Liste der unterstützten Sprachen für die Rechtschreib- und Semantiksuche.

queryLanguage

Gültige Werte für den Parameter "queryLanguage" werden in der folgenden Tabelle, in der Spalte "queryLanguage" angegeben und die Groß-/Kleinschreibung wird nicht beachtet. Der Standardwert für den Parameter als Ganzes ist "en-us". Innerhalb jeder Sprache gibt es eine Standardvariante für jeden zweistelligen Sprachcode. Wenn Sie beispielsweise "es" angeben, wird standardmäßig "es-us" verwendet. Der parameter queryLanguage ist für eine Abfrageanforderung erforderlich, die "queryType=semantic" oder "speller=lexicon" enthält. Es gibt nur einen QueryLanguage-Wert für die gesamte Anforderung, und dieser Wert wird für semantische Rangfolge, Beschriftungen, Antworten und Rechtschreibprüfung verwendet (für einzelne Features gibt es keine Außerkraftsetzung).

Zurzeit variiert die Sprachunterstützung je nach Feature. Nur Englisch, Spanisch, Französisch und Deutsch werden für die vollständigen Features unterstützt, beachten Sie jedoch, dass die Rechtschreibprüfung weniger Varianten implementiert.

Wenn Sie einen Sprachcode angeben, der von einem bestimmten Feature nicht unterstützt wird, z. B. EN-GB mit Rechtschreibprüfung, gibt der Dienst HTTP 400 zurück.

Weitere Informationen zur Verwendung der einzelnen Features finden Sie unter Aktivieren der semantischen Rangfolge und beschriftungen, Zurückgeben einer semantischen Antwortund Hinzufügen der Rechtschreibprüfung zu Abfragen.

Die Bezeichnung "(Vorschau)" gibt an, dass Validierungstests für alle Features (semantische Rangfolge, Beschriftungen, Antworten und Rechtschreibprüfung) entweder fortlaufend oder ausstehend sind. Wir empfehlen die Verwendung aller Sprachvarianten in der folgenden Tabelle, empfehlen aber weitere Tests von Vorschausprachen, um sicherzustellen, dass die Ergebnisse für Ihre Inhalte gültig sind. Sprachen mit einem Häkchen und keine Vorschaubezeichnung wurden mit entsprechenden Datensätzen überprüft, wobei messbare Relevanz gewonnen wurde.

Sprache	queryLanguage	Semantischer Rangierer und Beschriftungen	Semantische Antwort	Buchstabierer
Englisch [`en`]	`en, en-US` (Standard), `en-GB`, `en-IN`, `en-CA`, `en-AU`	✔️	✔️	✔️ (`en, en-US`)
Französisch [`fr`]	`fr`, `fr-FR` (Standard), `fr-CA`	✔️	✔️	✔️ (`fr, fr-FR`)
Deutsch [`de`]	`de, de-DE` (Standard)	✔️	✔️	✔️ (`de, de-DE`)
Spanisch [`es`]	`es, es-ES` (Standard), `es-MX`	✔️	✔️	✔️ (`es, es-ES`)
Italienisch [`it`]	`it, it-IT` (Standard)	✔️	✔️
Japanisch [`ja`]	`ja, ja-JP` (Standard)	✔️	✔️ (Vorschau)
Chinesisch [`zh`]	`zh, zh-CN` (Standard), `zh-TW`	✔️	✔️ (Vorschau)
Portugiesisch [`pt`]	`pt, pt-BR` (Standard), `pt-PT`	✔️	✔️ (Vorschau)
Niederländisch [`nl`]	`nl, nl-BE, nl-NL` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)	✔️ (`nl, nl-NL`)
Arabisch [`ar`]	`ar, ar-SA` (Standard), `ar-EG, ar-MA, ar-KW, ar-JO`	✔️ (Vorschau)	✔️ (Vorschau)
Armenisch	`hy-AM` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Bangla	`bn-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Baskisch	`eu-ES` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Bulgarisch [`bg`]	`bg, bg-BG` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Katalanisch [`ca`]	`ca, ca-ES` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Kroatisch [`hr`]	`hr, hr-HR` (Standard), hr-BA	✔️ (Vorschau)	✔️ (Vorschau)
Tschechisch [`cs`]	`cs, cs-CZ` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Dänisch [`da`]	`da, da-DK` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Estland [`et`]	`et, et-EE` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Finnisch [`fi`]	`fi, fi-FI` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Galizisch	`gl-ES` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Griechisch [`el`]	`el, el-GR` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Gujarati	`gu-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Hebräisch	`he-IL` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Hindi [`hi`]	`hi, hi-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Ungarisch [`hu`]	`hu, hu-HU` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Isländisch [`is`]	`is, is-IS` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Indonesien [`id`]	`id, id-ID` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Irisch	`ga-IE` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Kannada	`kn-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Koreanisch [`ko`]	`ko, ko-KR` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Lettisch [`lv`]	`lv, lv-LV` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Litauisch [`lt`]	`lt, lt-LT` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Malayalam	`ml-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Malaysian [`ms`]	`ms, ms-MY` (Standard), `ms-BN`	✔️ (Vorschau)	✔️ (Vorschau)
Marathi	`mr-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Norwegisch [`no`]	nein, no-NO (Standard), nb-NO	✔️ (Vorschau)	✔️ (Vorschau)
Persisch	`fa-AE` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Polnisch [`pl`]	`pl, pl-PL` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Punjabi	`pa-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Rumänisch [`ro`]	`ro, ro-RO` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Russisch [`ru`]	`ru, ru-RU` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Serbisch [`sr`] (Kyrillisch oder Lateinisch)	`sr, sr-BA` (Standard), `sr-ME, sr-RS`	✔️ (Vorschau)	✔️ (Vorschau)
Slowakisch [`sk`]	`sk, sk-SK` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Slowenisch [`sl`]	`sl, sl-SL` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Tamil [`ta`]	`ta, ta-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Schwedisch [`sv`]	`sv, sv-SE` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Telugu	`te-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Thai [`th`]	`th, th-TH` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Türkisch [`tr`]	`tr, tr-TR` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Ukrainisch [`uk`]	`uk, uk-UA` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Urdu	`ur-PK` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Vietnamesisch [`va`]	`va, vi-VN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)

Freigeben über