Dokumente durchsuchen (Vorschau DER REST-API)

Artikel
11/13/2023

Gilt für: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Wichtig

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

Abfrageparameter "vectors" , 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 das Semantikranking auf bestimmte Felder.
"captions" gibt Ausdrücke zurück, die aus Schlüsselpassagen in den semantisch am höchsten bewerteten 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 der Felder fest, die zum Formulieren von Beschriftungen und Antworten verwendet werden. Dieser Ansatz wurde in 2021-04-30-Preview durch "semanticConfiguration" ersetzt und ist jetzt veraltet.
"Rechtschreibprüfung" ermöglicht die Rechtschreibkorrektur bei der Abfrageeingabe.
"queryLanguage" ist sowohl für "queryType=semantic" als auch für "speller" erforderlich.
"featuresMode" entpackt eine Suchbewertung und meldet die Häufigkeit pro Feld, die Ähnlichkeitsbewertung pro Feld und die Anzahl eindeutiger Übereinstimmungen pro Feld.

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 formen. 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 Aktion "Suchen" 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 es größere Filter als GET zulässt.

Bei POST stellt die Anzahl der Klauseln in einem Filter die Einschränkung dar, nicht die Größe der unformatierten Filterzeichenfolge, da die maximal zulässige Größe für Anforderungen bei POST etwa 16 MB ist. Auch wenn die Größe der POST-Anforderung 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/Dokumentation	Erforderlich. Gibt die Dokumentenauflistung eines benannten Indexes an. Der Name eines Indexalias kann auch anstelle des Indexnamens verwendet werden.
Abfrageparameter (query parameters)	Abfrageparameter werden für den URI für GET-Anforderungen und im Anforderungstext für POST-Anforderungen angegeben.
api-version	Erforderlich. Die aktuelle Version ist `2023-07-01-Preview`. Weitere Versionen finden Sie unter API-Versionen .

URL-Codierungsempfehlungen

Denken Sie daran, beim direkten Aufrufen der GET-REST-API bestimmte Abfrageparameter URL-codieren zu müssen. Für einen Vorgang Dokumente durchsuchen ist möglicherweise die URL-Codierung für die folgenden Abfrageparameter erforderlich:

search
$filter
Facet
highlightPreTag
highlightPostTag

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

Darüber hinaus ist die URL-Codierung nur erforderlich, wenn Sie die REST-API direkt mittels „GET“ aufrufen. Bei Verwendung von POST oder der Azure AI Search .NET-Clientbibliothek, die die Codierung für Sie verarbeitet, ist keine URL-Codierung erforderlich.

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder	BESCHREIBUNG
Content-Type	Erforderlich. Legen Sie diesen Wert auf "application/json" fest.
api-key	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 bei Ihrem Suchdienst authentifiziert. Abfrageanforderungen für die Dokumentensammlung können entweder einen Administratorschlüssel oder einen Abfrageschlüssel als API-Schlüssel angeben. Der Abfrageschlüssel wird für schreibgeschützte Vorgänge für die Dokumentensammlung verwendet. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung .

Felder

BESCHREIBUNG

Content-Type

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

api-key

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 bei Ihrem Suchdienst authentifiziert. Abfrageanforderungen für die Dokumentensammlung können entweder einen Administratorschlüssel oder einen Abfrageschlüssel als API-Schlüssel angeben. Der Abfrageschlüssel wird für schreibgeschützte Vorgänge für die Dokumentensammlung verwendet. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung .

Anforderungstext

GET: Keiner

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 der Teilsuchantworten

Manchmal kann Azure AI Search nicht alle angeforderten Ergebnisse in einer einzigen Suchantwort zurückgeben. Eine partielle Antwort kann aus verschiedenen Gründen auftreten, z. B. wenn die Abfrage zu viele Dokumente zurückgibt, indem $top nicht angegeben wird, oder wenn ein Wert für $top angegeben wird, der zu groß ist. In solchen Fällen enthält Azure AI Search die @odata.nextLink Anmerkung im Antworttext und auch @search.nextPageParameters , wenn es sich um eine POST-Anforderung handelt. Die Werte dieser Anmerkungen können Sie zum Formulieren einer weiteren Suchanforderung zum Abrufen des nächsten Teils der Suchantwort verwenden. Dieses Verhalten wird als Fortsetzung der ursprünglichen Suchanforderung bezeichnet, und die Anmerkungen werden als Fortsetzungstoken bezeichnet. Im Beispiel im Abschnitt Antwort finden Sie Details zur Syntax dieser Anmerkungen und deren Anzeige im Antworttext.

Die Gründe, aus denen Azure KI Search Fortsetzungstoken zurückgeben kann, sind implementierungsspezifisch und können sich ändern. Stabile Clients sollten für die Behandlung von Fällen bereit sein, in denen weniger Dokumente als erwartet zurückgegeben werden und ein Fortsetzungstoken zum Abrufen von Dokumenten enthalten ist. 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, muss auch für alle Fortsetzungsanforderungen, die Sie senden, GET verwendet werden (dasselbe gilt für POST).

Hinweis

Der Zweck von @odata.nextLink und @search.nextPageParameters besteht darin, den Dienst vor Abfragen zu schützen, die zu viele Ergebnisse anfordern, und nicht, um einen allgemeinen Mechanismus für das Paging bereitzustellen. Wenn Sie Ergebnisse durchblättern möchten, verwenden Sie $top und $skip zusammen. Wenn Sie beispielsweise Seiten der 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 usw. haben.

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 wird. Bei manchen Parametern wird für „GET“ eine etwas andere Syntax verwendet als für „POST“. Diese Unterschiede sind in der folgenden Tabelle aufgeführt.

Name	Typ	BESCHREIBUNG
Antworten (Vorschau)	Zeichenfolge	Optional. Gültige Werte sind "none" und "extractive". Der Standardwert ist "none". Dieser Parameter ist nur gültig, wenn der Abfragetyp "semantic" ist. Bei Festlegung auf "extrahierend" formuliert und gibt die Abfrage Antworten aus wichtigen Passagen in den dokumenten mit dem höchsten semantischen Rang zurück. Der Standardwert ist eine Antwort, aber Sie können 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 wird, muss im Zielfeld ausführlicher Inhalt vorhanden sein, der wie eine Antwort aussieht. Die Sprachmodelle, die für Antworten verwendet werden, werden trainiert, um Antworten zu erkennen und nicht zu generieren. Darüber hinaus muss die Abfrage selbst wie eine Frage aussehen.
api-version	Zeichenfolge	Erforderlich. Version der für die Anforderung verwendeten REST-API. 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 Dokumente durchsuchen mit GET oder POST aufrufen.
Untertitel (Vorschau)	Zeichenfolge	Optional. Gültige Werte sind "none" und "extractive". Der Standardwert ist "none". Dieser Parameter ist nur gültig, wenn der Abfragetyp "semantic" ist. Bei Festlegung auf "extrahierend" gibt die Abfrage Beschriftungen zurück, die aus Schlüsselpassagen in den dokumenten mit dem höchsten Rang extrahiert wurden. Wenn Beschriftungen auf "extractiv" festgelegt sind, ist die Hervorhebung standardmäßig aktiviert und kann konfiguriert werden, indem das Pipezeichen '\|' gefolgt von der Option "highlight-true</false>" angefügt wird, z. B. "extractive\|highlight-true".
$count	boolean	Optional. Gültige Werte sind „true“ und „false“. Der Standardwert ist "false". Wenn dieser Parameter mit POST aufgerufen wird, heißt dieser Parameter count anstelle von $count. Gibt an, ob die Gesamtzahl 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 dokumente, die aktiv hinzugefügt, aktualisiert oder gelöscht werden, unter- oder übermäßig meldet. Wenn Sie nur die Anzahl ohne Dokumente abrufen möchten, können Sie $top=0 verwenden.
Facet oder Facetten	Zeichenfolge	Optional. Ein Feld, nach dem facetiert werden soll, wobei das Feld als "facetable" zugeordnet wird. Bei Aufruf mit GET `facet` ist ein Feld (`facet: field1`). Wenn er mit POST aufgerufen wird, wird dieser Parameter anstelle von `facet` benannt `facets` und als Array (`facets: [field1, field2, field3]`) angegeben. Die Zeichenfolge kann Parameter zum Anpassen der Faceting enthalten, ausgedrückt als durch Trennzeichen getrennte Name-Wert-Paare. Gültige Werte sind "count", "sort", "values", "interval" und "timeoffset". "Count" ist die maximale Anzahl von Facettenbegriffen; Der Standardwert ist 10. Es gibt keine Obergrenze für die Anzahl von Begriffen, aber höhere Werte beeinträchtigen die Leistung, insbesondere wenn das Facettenfeld eine große Anzahl eindeutiger Begriffe enthält. Beispielsweise ruft "facet=category,count:5" die obersten fünf Kategorien in Facetergebnissen ab. Wenn der count-Parameter kleiner als die Anzahl eindeutiger Begriffe ist, sind die Ergebnisse möglicherweise nicht korrekt. Dies liegt an der Art, wie Facettenabfragen über Shards hinweg verteilt werden. Um eine genaue Anzahl für alle Shards zu erhalten, können Sie die Anzahl auf 0 (null) oder auf einen Wert festlegen, der größer oder gleich der Anzahl eindeutiger Werte im feld "Facetable" ist. Der Kompromiss ist eine erhöhte Latenz. "sort" 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 obersten drei Kategorien in Facetergebnissen in absteigender Reihenfolge nach der Anzahl der Dokumente mit jedem Stadtnamen ab). Wenn die drei obersten Kategorien Budget, Motel und Luxury sind und Budget fünf Treffer hat, Hat Motel sechs und Luxus hat vier, dann sind die Buckets in der Reihenfolge Motel, Budget, Luxury. Für -value erzeugt "facet=rating,sort:-value" Buckets für alle möglichen Bewertungen in absteigender Reihenfolge nach Wert (wenn die Bewertungen z. B. zwischen 1 und 5 liegen, werden die Buckets unabhängig davon, wie viele Dokumente den einzelnen Bewertungen entsprechen, 5, 4, 3, 2, 1) sortiert. "values" kann auf numerische Werte mit Pipetrennzeichen oder Edm.DateTimeOffset festgelegt werden, die einen dynamischen Satz von Faceteintragswerten angeben (z. B. "facet=baseRate,values:10 \| 20" erzeugt drei Buckets: einen für Den Basissatz 0 bis 10, einen für 10 bis 20 und einen für 20 und höher). Eine Zeichenfolge "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" erzeugt zwei Buckets: einen für Hotels, die vor Februar 2010 renoviert wurden, und einen 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. "interval" ist ein ganzzahliges Intervall, das größer als 0 für Zahlen ist, oder Minute, Stunde, Tag, Woche, Monat, Quartal, Jahr für Datumsangaben. Beispielsweise erzeugt "facet=baseRate,interval:100" Buckets basierend auf Basisratenbereichen der Größe 100. Wenn alle Basissätze zwischen 60 und 600 US-Dollar 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 einen Bucket für jedes Jahr, in dem Hotels renoviert wurden. "timeoffset" kann auf ([+-]hh:mm, [+-]hhmm oder [+-]hh) festgelegt werden. Bei Verwendung muss der timeoffset-Parameter mit der Option interval kombiniert werden, und nur, wenn er auf ein Feld vom Typ Edm.DateTimeOffset angewendet wird. Der Wert gibt den Offset zur UTC-Zeit für die Festlegung der zeitlichen Grenzwerte an. Beispiel: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" verwendet die Tagesgrenze, die um 01:00:00 UTC beginnt (Mitternacht in der Zielzeitzone). Count und Sortierung können in derselben Facettenspezifikation kombiniert werden, aber sie können nicht mit Intervallen oder Werten kombiniert werden, und Intervall und Werte können nicht miteinander kombiniert werden. Intervallfacetten zur Datumszeit werden basierend auf der UTC-Zeit berechnet, wenn kein Zeitoffset angegeben wird. Beispiel: Für "facet=lastRenovationDate,interval:day" beginnt die Tagesgrenze bei 00:00:00 UTC.
featuresMode (Vorschau)	boolean	Optional. Gültige Werte sind "enabled" und "disabled". Der Standardwert ist "disabled". Ein -Wert, der angibt, ob die Ergebnisse Abfrageergebnisfeatures enthalten sollen, die zum Berechnen der Relevanzbewertung eines Dokuments in Bezug auf die Abfrage verwendet werden, z. B. pro Feldähnlichkeit. Verwenden Sie "enabled", um weitere Abfrageergebnisfeatures verfügbar zu machen: pro Feldähnlichkeitsbewertung, Häufigkeit pro Feldausdruck und Anzahl der übereinstimmenden eindeutigen Token pro Feld. Weitere Informationen finden Sie unter Ähnlichkeit und Bewertung.
$filter	Zeichenfolge	Optional. Ein strukturierter Suchausdruck in Standard-OData-Syntax. In einem Filter können nur filterbare Felder verwendet werden. Wenn dieser Parameter mit POST aufgerufen wird, heißt dieser Parameter filter anstelle von $filter. Ausführliche Informationen zur Teilmenge der OData-Ausdrucksgrammatik, die von Azure KI Search unterstützt wird, finden Sie unter OData-Ausdruckssyntax für Azure KI Search .
highlight	Zeichenfolge	Optional. Eine Reihe von durch Komma getrennten Feldnamen, die für Treffermarkierungen verwendet werden. Nur durchsuchbare Felder können für die Trefferherhebung verwendet werden. Standardmäßig gibt Azure KI Search bis zu fünf Hervorhebungen pro Feld zurück. Der Grenzwert kann pro Feld konfiguriert werden, indem "-<max # of highlights>" 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	Zeichenfolge	Optional. Wird standardmäßig auf `"</em>"` festgelegt. Ein Zeichenfolgentag, das an den hervorgehobenen Ausdruck angefügt wird. Muss mit highlightPreTag festgelegt werden. Reservierte Zeichen in der URL müssen mit Prozentzeichen codiert werden (z. B. %23 anstelle von #).
highlightPreTag	Zeichenfolge	Optional. Wird standardmäßig auf `"</em>"` festgelegt. Ein Zeichenfolgentag, das dem hervorgehobenen Begriff vorangestellt wird. Muss mit highlightPostTag festgelegt werden. Reservierte Zeichen in der URL müssen mit Prozentzeichen codiert werden (z. B. %23 anstelle von #).
minimumCoverage	integer	Optional. Gültige Werte sind eine Zahl zwischen 0 und 100, die den Prozentsatz des Indexes angibt, der verfügbar sein muss, um die Abfrage zu warten, bevor sie als Erfolg gemeldet werden kann. Standardwert ist "100". Eine hundertprozentte Abdeckung bedeutet, dass alle Shards auf die Anforderung reagiert haben (weder Probleme mit der Dienstintegrität noch wartungsaktivitäten reduzierte Abdeckung). Unter der Standardeinstellung gibt die vollständige Abdeckung HTTP-status Code 503 zurück. Die Senkung der Mindestabdeckung kann nützlich sein, wenn 503-Fehler auftreten und Sie die Wahrscheinlichkeit eines Abfrageerfolgs erhöhen möchten, insbesondere für Dienste, die für ein Replikat konfiguriert sind. Wenn Sie minimumCoverage und Search erfolgreich festlegen, 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 sind nicht alle übereinstimmenden Dokumente garantiert in den Suchergebnissen vorhanden, aber wenn die Suchverfügbarkeit wichtiger als der Rückruf ist, kann die Verringerung der Abdeckung eine praktikable Strategie zur Entschärfung sein.
$orderby	Zeichenfolge	Optional. Eine Liste von Ausdrücken (durch Kommas voneinander getrennt), nach denen die Ergebnisse sortiert werden sollen. Wenn er mit POST aufgerufen wird, wird dieser Parameter orderby anstelle von $orderby genannt. Jeder Ausdruck kann entweder ein Feldname oder ein Aufruf der Funktion geo.distance() sein. Jedem Ausdruck kann "asc" folgen, um aufsteigend anzugeben, und "desc", um absteigend anzugeben. Wenn im Sortierfeld NULL-Werte vorhanden sind, werden NULL-Werte zuerst in aufsteigender Reihenfolge und zuletzt in absteigender Reihenfolge angezeigt. Standardmäßig wird in aufsteigender Reihenfolge sortiert. Verknüpfungen werden durch die Ergebnisstände von Dokumenten getrennt. Wenn kein $orderby angegeben ist, wird die Standardsortierreihenfolge nach dokumentgleicher Bewertung absteigend. Es gibt ein Limit von 32 Klauseln für $orderby.
queryLanguage (Vorschau)	Zeichenfolge	Optional. Gültige Werte sind eine unterstützte Sprache. Standardmäßig wird "en-us" festgelegt. 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 Untertitel oder Antwort extrahieren. Die für queryLanguage verwendeten Bibliotheken sind unabhängig von anderen gebietsschemabasierten Feldattributen, z. B . Sprachanalysetools , die für die Indizierung und die Volltextsuche verwendet werden.
queryType	Zeichenfolge	Optional. Gültige Werte sind "simple", "full" oder "semantic" (Vorschau). Der Standardwert ist „simple“. Dieser Wert wird für die Vektorsuche ignoriert, gilt aber für die Textsuche in Hybridszenarien. "simple" interpretiert Abfragezeichenfolgen mithilfe der einfachen Abfragesyntax , die Symbole wie `+`, ``und `""`zulässt. Abfragen werden standardmäßig für alle durchsuchbaren Felder (oder felder, die in searchFields angegeben sind) in jedem Dokument ausgewertet. "full" interpretiert Abfragezeichenfolgen mithilfe der vollständigen Lucene-Abfragesyntax , die feldspezifische und gewichtete Suchvorgänge ermöglicht. Die Bereichssuche in der Lucene-Abfragesprache wird zugunsten von $filter nicht unterstützt, die ähnliche Funktionen bietet. " Semantik" verbessert die Genauigkeit der Suchergebnisse, indem die Top 50-Übereinstimmungen mithilfe eines im Bing-Korpus trainierten Rangfolgemodells für abfragen, die in natürlicher Sprache im Gegensatz zu Schlüsselwörtern ausgedrückt werden. 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 ersten 3 Antworten zurückgeben möchten, wenn die Abfrageeingabe in natürlicher Sprache formuliert wurde ("was ist ein ...*), und Sie können optional Untertitel festlegen, um Schlüsselpassagen aus den am höchsten bewerteten Dokumenten zu extrahieren.
scoringParameter	Zeichenfolge	Optional. Gibt die Werte für jeden parameter an, der in einer Bewertungsfunktion definiert ist (z. B. referencePointParameter) im 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. Trennen Sie für Bewertungsprofile, die eine Funktion enthalten, die Funktion von ihrer Eingabeliste durch ein `-` Zeichen. Beispielsweise wäre eine Funktion namens `"mylocation"` "&scoringParameter=mylocation--122.2,44.8". Der erste Bindestrich trennt den Funktionsnamen von der Wertliste, während der zweite Bindestrich Teil des ersten Werts ist (in diesem Beispiel längengrad). Für Bewertungsparameter, z. B. für tagaufstufen, die Kommas enthalten können, können Sie alle werte in der Liste mithilfe einzelner Anführungszeichen mit Escapezeichen versehen. Wenn die Werte selbst einfache Anführungszeichen enthalten, können Sie sie verdoppeln, um sie mit Escapezeichen zu versehen. Angenommen, Sie haben einen Tag boosting-Parameter namens `"mytag"` und möchten die Tagwerte "Hello, O'Brien" und "Smith" erhöhen. Die Abfragezeichenfolgenoption lautet dann "&scoringParameter=mytag-'Hello, O''Brien',Smith". Anführungszeichen sind nur für Werte erforderlich, die Kommas enthalten.
scoringProfile	Zeichenfolge	Optional. Der Name eines Bewertungsprofils zum Auswerten von Übereinstimmungsbewertungen für den Vergleich von Dokumenten, um die Ergebnisse zu sortieren.
scoringStatistics	Zeichenfolge	Optional. Gültige Werte sind "local" oder "global". Standardmäßig wird "local" festgelegt. Geben Sie an, ob Bewertungsstatistiken wie die Dokumenthäufigkeit global (über alle Shards hinweg) berechnet werden sollen, um eine konsistentere Bewertung zu erzielen, oder lokal (auf dem aktuellen Shard), um eine geringere Latenz zu erzielen. Weitere Informationen finden Sie unter Bewertungsstatistiken in Azure AI Search. Bewertungsstatistiken werden immer lokal für Begriffe berechnet, die die Fuzzy-Suche ('~')verwenden.
search	Zeichenfolge	Optional. Der zu suchende Text. Dieser Wert wird für die Vektorsuche ignoriert, gilt aber für die Textsuche in Hybridszenarien. In REST-APIs werden standardmäßig alle durchsuchbaren Felder durchsucht, es sei denn, searchFields ist angegeben. Im Index wird Text in einem durchsuchbaren Feld tokenisiert, sodass mehrere Begriffe durch Leerzeichen getrennt werden können (z. B. "search=hello world"). Verwenden Sie für die Übereinstimmung mit einem beliebigen Begriff `` (dies kann bei booleschen Filterabfragen nützlich sein). Das Auslassen dieses Parameters hat dieselbe Wirkung wie das Festlegen auf ``. Weitere Informationen zur Suchsyntax finden Sie unter Einfache Abfragesyntax. Ergebnisse können manchmal überraschend sein, wenn Abfragen über durchsuchbare Felder erfolgen. Der Tokenizer enthält die Logik zum Behandeln von Fällen, die in englischem Text üblich sind, z. B. Apostrophe, Kommas in Zahlen usw. 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 Begriffe im Suchparameter zu trennen.
searchMode	Zeichenfolge	Optional. Gültige Werte sind "any" oder "all" Standardwerte auf "any". Gibt an, ob einige oder alle Suchbegriffe übereinstimmen müssen, damit das Dokument als Übereinstimmung zählt.
searchFields	Zeichenfolge	Optional. Die Liste von Feldnamen (durch Kommas voneinander getrennt), die nach dem angegebenen Text durchsucht 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	Zeichenfolge	Optional. 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 anders angegeben oder auf `*`gesetzt, werden alle im Schema als abrufbar gekennzeichnete Felder in die Projektion einbezogen. Wenn er mit POST aufgerufen wird, heißt dieser Parameter select anstelle von $select.
semanticConfiguration (Vorschau)	Zeichenfolge	Optional. 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 Semantikabfrage.
sessionID	Zeichenfolge	Optional. Mithilfe von sessionId können Sie die Konsistenz der Relevanzbewertung für Suchdienste mit mehreren Replikaten verbessern. Bei Konfigurationen mit mehreren Replikaten kann es geringfügige Unterschiede zwischen den Relevanzbewertungen einzelner Dokumente für dieselbe Abfrage geben. Wenn eine Sitzungs-ID bereitgestellt wird, bemüht sich der Dienst nach besten Kräften, eine bestimmte Anforderung an dasselbe Replikat für diese Sitzung weiterzuleiten. Seien Sie vorsichtig, da die wiederholte Wiederverwendung der gleichen Sitzungs-ID-Werte 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 Bewertungskonsistenz.
$skip	integer	Optional. Die Anzahl der zu überspringenden Suchergebnisse. Wenn er mit POST aufgerufen wird, heißt dieser Parameter skip anstelle von $skip. Dieser Wert darf nicht größer als 100.000 sein. Wenn Sie Dokumente nacheinander scannen 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 aufweist (z. B. den Dokumentschlüssel), und $filter stattdessen mit einer Bereichsabfrage.
Rechtschreibprüfung (Vorschau)	String	Optional. Gültige Werte sind "none" und "lexicon". Der Standardwert ist "none". Verbessern Sie den Rückruf, indem Sie einzelne Suchabfragebegriffe rechtschreibkorrekturen. Sie können sie für einfache, vollständige und semantische Abfragetypen verwenden. Wenn er verwendet wird, erfordert der Rechtschreibparameter queryLanguage. Weitere Informationen und Beispiele finden Sie unter Hinzufügen der Rechtschreibprüfung zu Abfragen.
$top	integer	Optional. Die Anzahl der abzurufenden Suchergebnisse. Der Standardwert ist 50. Wenn er mit POST aufgerufen wird, heißt dieser Parameter top statt $top. Wenn Sie einen Wert angeben, der größer als 1000 ist und mehr als 1000 Ergebnisse vorliegen, werden nur die ersten 1000 Ergebnisse sowie ein Link zur nächsten Ergebnisseite zurückgegeben (siehe "@odata.nextLink" im folgenden Beispiel). Azure KI Search verwendet serverseitiges 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 " Dokumente durchsuchen" standardmäßig höchstens 50 Ergebnisse zurückgibt, wenn Sie $top nicht angeben. Wenn mehr als 50 Ergebnisse vorliegen, enthält die Antwort Informationen zum Abrufen der nächsten Seite von höchstens 50 Ergebnissen (siehe "@odata.nextLink" und "@search.nextPageParameters" in den folgenden Beispielen . Wenn Sie einen Wert größer als 1000 für $top angeben und mehr als 1000 Ergebnisse vorhanden sind, werden nur die ersten 1000 Ergebnisse zurückgegeben, zusammen mit Informationen zum Abrufen der nächsten Seite von höchstens 1000 Ergebnissen.
Vektoren (Vorschau)	array	Optional. 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 KI 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. Minimum ist 1 und Maximum 10.000. "Fields" 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

Bei erfolgreicher Antwort wird der Statuscode "200 OK" zurückgegeben. In diesem Artikel gibt es zwei Beispielantworten, jeweils eine für 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 Answers-Parameter angeben und wenn die Abfrage und die Zielfelder im Index Inhalte enthalten, die als Antwort erkannt werden können. Das @search.answers Array mit einem Schlüssel, Text und Hervorhebungen. Die Bewertung ist ein Indikator für die Stärke der Antwort.
"value" ist der Text der Antwort. wird @search.rerankerScore vom semantischen Rangfolgealgorithmus zugewiesen und zum Bewerten von Ergebnissen verwendet (@search.score stammt aus dem BM25-Ähnlichkeitsalgorithmus, der bei der Bewertung der ersten Ergebnisse verwendet wird). Beschriftungen enthalten Nur-Text und hervorgehobene Versionen. Dieses Beispiel wurde mithilfe von 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

Dieses Beispiel zeigt die Ausgabe "@search.features" aus einer Abfrage, die featuresMode enthält.

  {
    "@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 unter OData-Ausdruckssyntax für Azure KI Search.

Beispiel: einfache Suche

Suchen Sie mithilfe einer einfachen Abfragesyntax entsprechende Dokumente im Index. Diese Abfrage gibt Hotels zurück, deren durchsuchbare Felder die Begriffe "Komfort" und "Standort" aber nicht "Motel" enthalten:

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"  
    }

Tipp

Durch die Verwendung von searchMode=all wird der Standardwert von searchMode=any überschrieben, wodurch sichergestellt wird, dass -motel "AND NOT" bedeutet, nicht "OR NOT". Ohne searchMode=all wird "OR NOT" verwendet, womit Suchergebnisse erweitert anstatt eingeschränkt werden. Dies kann für manche Benutzer widersinnig sein.

Beispiel: vollständige Lucene-Suche

Suchen Sie Dokumente im Index mithilfe der Lucene-Abfragesyntax (siehe Lucene-Abfragesyntax in Azure AI Search). Bei dieser Abfrage werden Hotels zurückgegeben, bei denen das Kategoriefeld den Begriff „budget“ enthält und alle durchsuchbaren Felder die Wörter „recently renovated“ enthalten. Dokumente mit den Wörtern „recently renovated“ werden aufgrund des Term Boost-Werts (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 modell für die semantische Rangfolge 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. Parameter für Vektorabfragen umfassen die Vektorfelder, die sich im Gültigkeitsbereich der Abfrage befinden, die "k"-Anzahl der zurückzugebenden häufigsten Treffer und eine Vektordarstellung der Abfrageeingabe.

Das Hinzufügen eines "select"-Parameters ist hilfreich, wenn der Index Textfelder enthält. Übereinstimmung und Relevanz basieren auf Vektoren, aber Felder, die lesbare Inhalte enthalten, sind für benutzerfreundlichere Benutzer nützlicher, die die Ergebnisse lesen. 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 nach Datum sortierte Ergebnisse 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

Rufen Sie Dokumente ab, die einem speziellen 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: Facettensuche

Durchsuchen Sie in einer Facettensuche den Index, und rufen Sie Facetten 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 in einem Unterfeld befindet. Facetten zählen das übergeordnete Dokument (Hotels) und nicht die zwischengeschalteten Unterdokumente (Räume), sodass die Antwort die Anzahl der Hotels bestimmt, die über Zimmer in jedem Preis-Bucket verfügen.

Beispiel: Einschränken einer facettenten Abfrage

Wenn Sie einen Filter verwenden, schränken Sie das ergebnis der vorherigen Facettenabfrage ein, nachdem der Benutzer die 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: Facettensuche mit Grenzwerten für jede Kategorie

Legen Sie bei einer Facettensuche eine Obergrenze für die in einer Abfrage zurückgegebenen eindeutigen Begriffe fest. Der Standardwert ist 10, aber Sie können diesen Wert mithilfe des "count"-Parameters für das "facet"-Attribut erhöhen oder verringern. In diesem Beispiel werden Facets für den Ort zurückgegeben, die auf 5 begrenzt 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: Feldsuche

Durchsuchen des Indexes in bestimmten Feldern (z. B. ein Sprachfeld)

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 in mehreren Feldern. Beispiel: Sie können durchsuchbare Felder innerhalb desselben Index in mehreren Sprachen speichern und abfragen. Wenn englische und französische Beschreibungen im selben Dokument koexistieren, können Sie eine 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 planen, einen nach dem anderen abzufragen.

Beispiel: Pagingergebnisse

Rufen Sie die erste Seite von Elementen ab (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  
    }

Rufen Sie die zweite Seite von Elementen ab (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

Rufen Sie einen speziellen Satz von Feldern ab:

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 Treffermarkierungen 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: Georäumliche Suche

Durchsuchen Sie den Index, und geben Sie Dokumente zurück, die hinsichtlich der Entfernung zu einem Referenzstandort aufsteigend (zuerst die nächstgelegenen Dokumente) 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: "Find by me" (Relevanz von nahe gelegenen Standorten erhöhen)

Suchen 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" das Trennzeichen eines einzelnen Bindestrichs (-) auf. Es folgen 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 den vollständigen Index anstelle von Shards

Suchen Sie Dokumente im Index, während Sie eine konsistente Bewertung gegenüber einer geringeren Latenz bevorzugen. Diese Abfrage berechnet Dokumenthäufigkeiten für den gesamten Index und bemüht sich am besten, dasselbe Replikat für alle Abfragen innerhalb derselben "Sitzung" anzusprechen, 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: Bewertungsstatistiken (featuresMode)

Suchen Sie Dokumente im Index, und geben Sie eine Liste der Informationsabruffunktionen für jedes Ergebnis zurück, das die Bewertung zwischen dem übereinstimmende Dokument und der Abfrage beschreibt. Die Abfrage berechnet auch Dokumenthäufigkeiten für den gesamten Index, 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 enthält search.features , sieht 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 Standard Tabelle abzudecken.

Link	BESCHREIBUNG
queryLanguage	Liste der unterstützten Sprachen für die Rechtschreib- und Semantiksuche.

queryLanguage

Gültige Werte für den queryLanguage-Parameter werden in der folgenden Tabelle in der Spalte "queryLanguage" angegeben, wobei die Groß-/Kleinschreibung nicht beachtet wird. 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 queryLanguage-Parameter 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 Rechtschreibweise verwendet (es gibt keine Überschreibung für einzelne Features).

Derzeit variiert die Sprachunterstützung je nach Feature. Nur Englisch, Spanisch, Französisch und Deutsch werden für den gesamten Funktionsumfang 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 von semantischen Rangfolgen und Beschriftungen, Zurückgeben einer semantischen Antwort und Hinzufügen der Rechtschreibprüfung zu Abfragen.

Die Bezeichnung "(Vorschau)" gibt an, dass die Validierungstests für alle Features (semantische Rangfolge, Untertitel, Antworten und Rechtschreibprüfung) entweder ausgeführt oder ausstehend sind. Wir empfehlen die Verwendung aller Sprachvarianten in der folgenden Tabelle, empfehlen jedoch weitere Tests von Vorschausprachen, um sicherzustellen, dass die Ergebnisse für Ihre Inhalte gültig sind. Sprachen mit einem Häkchen und ohne Vorschaubezeichnung wurden mit entsprechenden Datasets mit messbarem Relevanzgewinn überprüft.

Sprache	queryLanguage	Semantischer Rangfolger und Beschriftungen	Semantische Antwort	Rechtschreibprüfung
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)
Bengalisch	`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)
Estnisch [`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)
Indonesisch [`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)
Malaysisch [`ms`]	`ms, ms-MY` (Standard), `ms-BN`	✔️ (Vorschau)	✔️ (Vorschau)
Marathi	`mr-IN` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Norwegisch [`no`]	no, no-NO (Standard), nb-NO	✔️ (Vorschau)	✔️ (Vorschau)
Persisch	`fa-AE` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Polnisch [`pl`]	`pl, pl-PL` (Standard)	✔️ (Vorschau)	✔️ (Vorschau)
Pandschabi	`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)
Thailändisch [`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)