Dokumente durchsuchen (Azure AI Search-REST-API)

Artikel
11/13/2023

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. Ab der API-Version 2021-04-30-Preview können Sie auch einen Indexalias verwenden, um einen bestimmten Index als Ziel zu verwenden, anstatt den Indexnamen selbst zu verwenden.

Sie können GET oder POST verwenden. 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 in der Regel 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 dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
[Indexname]/Dokumentation	Erforderlich. Gibt die Dokumentenauflistung eines benannten Indexes an.
[Abfrageparameter]	Abfrageparameter werden für den URI für GET-Anforderungen und im Anforderungstext für POST-Anforderungen angegeben.
api-version	Erforderlich. Die aktuelle stabile Version ist `api-version=2020-06-30`. Weitere Versionen finden Sie unter API-Versionen . Bei Abfragen wird die api-version immer als URI-Parameter für GET und POST angegeben.

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

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "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",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Fortsetzung der Teilsuchantworten

Manchmal kann Azure AI Search nicht alle angeforderten Ergebnisse in einer einzigen Suchantwort zurückgeben. Dafür gibt es verschiedene Gründe, z. B. wenn die Abfrage zu viele Dokumente anfordert, da $top nicht angegeben ist, oder einen zu großen Wert für $top angibt. 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. Dies wird als Fortsetzung der ursprünglichen Suchanforderung bezeichnet, und die Anmerkungen werden in der Regel als Fortsetzungstoken bezeichnet. Weitere Informationen zur Syntax dieser Anmerkungen und zur Anzeige im Antworttext finden Sie im folgenden Beispiel in Antwort.

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 z. B. Seiten der Größe 10 wünschen, sollte Ihre erste Anforderung über und $skip=0verfügen$top=10, die zweite Anforderung sollte $top=10 und haben, $skip=10die dritte Anforderung und und $skip=20usw. haben$top=10.

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 unten wie zutreffend aufgeführt.

Name	Typ	BESCHREIBUNG
api-version	Zeichenfolge	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 Dokumente suchen mit GET oder POST aufrufen.
`$count`	boolean	Optional. Gültige Werte sind „true“ und „false“. 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. Dies ist die Anzahl aller Dokumente, die den Such- und $filter-Parametern entsprechen, wobei und ignoriert `$top` wird `$skip`. Das Festlegen dieses Werts auf "true" kann die Leistung beeinträchtigen. Count ist richtig, wenn der Index stabil ist, aber dokumente, die aktiv hinzugefügt, aktualisiert oder gelöscht werden, unter oder überpromittiert. Wenn Sie nur die Anzahl ohne Dokumente abrufen möchten, können Sie =0 verwenden `$top`.
Facet oder Facetten	Zeichenfolge	Optional. Ein Feld zum Facetieren, in dem das Feld als "facetable" zugeordnet wird. Wenn mit GET aufgerufen wird, `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 kommagetrennte Name-Wert-Paare. Gültige Parameter 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 fünf besten Kategorien in Facetergebnissen ab. Wenn der count-Parameter kleiner als die Anzahl eindeutiger Begriffe ist, sind die Ergebnisse möglicherweise nicht richtig. Dies liegt an der Art, wie Facettenabfragen über Shards hinweg verteilt werden. Sie können die Anzahl auf 0 oder auf einen Wert festlegen, der größer oder gleich der Anzahl eindeutiger Werte im Gesichtsfeld ist, um eine genaue Anzahl für alle Shards zu erhalten. Der Kompromiss ist eine erhöhte Latenz. "sort" kann auf "count", "-count", "value", "-value" festgelegt werden. Verwenden Sie count, 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 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 5 Treffer hat, Motel hat 6 und Luxus hat 4, 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 beispielsweise von 1 bis 5 liegen, werden die Buckets unabhängig davon, wie viele Dokumente mit den einzelnen Bewertungen übereinstimmen, 5, 4, 3, 2, 1) sortiert. "Values" kann auf numerische Werte mit Pipetrennzeichen oder Edm.DateTimeOffset festlegen, die einen dynamischen Satz von Faceteintragswerten angeben (z. B. "facet=baseRate,values:10 \| 20" erzeugt drei Buckets: einen für basisrate 0 bis aber nicht einschl. 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 aufgeführt werden, um die erwarteten Ergebnisse zu erhalten. "Intervall" ist ein ganzzahliges Intervall größer als 0 für Zahlen, oder Minute, Stunde, Tag, Woche, Monat, Quartal, Jahr für Datumszeitwerte. Beispielsweise erzeugt "facet=baseRate,interval:100" Buckets basierend auf Basis von Basisratenbereichen der Größe 100. Wenn alle Basiskurse 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 Intervalloption kombiniert werden, und das 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 (Mitternacht in der Zielzeitzone) beginnt. Anzahl 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 timeoffset nicht angegeben wird. Beispiel: Für "facet=lastRenovationDate,interval:day" beginnt die Tagesgrenze um 00:00:00 UHR UTC.
$filter	Zeichenfolge	Optional. Ein strukturierter Suchausdruck in Standard-OData-Syntax. In einem Filter können nur filterbare Felder verwendet werden. Beim Aufrufen mit POST wird dieser Parameter filter anstelle von $filter genannt. Ausführliche Informationen zur Teilmenge der von Azure AI Search unterstützten OData-Ausdrucksgrammatik 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 zur Treffermarkierung verwendet werden. Standardmäßig gibt Azure AI Search bis zu 5 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 3 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.
queryType	Zeichenfolge	Optional. Gültige Werte sind "einfach" oder "vollständig". Der Standardwert ist „simple“. "einfach" 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 nicht zugunsten von $filter unterstützt, die ähnliche Funktionen bietet.
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 (längengrad in diesem Beispiel). Für Bewertungsparameter, z. B. für die Tag-Verstärkung, die Kommas enthalten können, können Sie alle werte in der Liste mit Escapezeichen versehen, indem Sie einfache Anführungszeichen verwenden. 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". Der Standardwert ist "local". Geben Sie an, ob Bewertungsstatistiken wie z. B. die Dokumenthäufigkeit global (über alle Shards hinweg) für eine konsistentere Bewertung oder lokal (im aktuellen Shard) für eine geringere Latenz berechnet werden sollen. Weitere Informationen finden Sie unter Bewertungsstatistiken in Azure AI Search. Bewertungsstatistiken werden immer lokal für Begriffe berechnet, die die Fuzzysuche ("~") verwenden.
search	Zeichenfolge	Optional. Der zu suchende Text. Alle durchsuchbaren Felder werden standardmäßig 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 Sie durchsuchbare Felder abfragen. 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" und nicht den einzelnen Begriffen "123" und "456", da Kommas als Tausendertrennzeichen für große Zahlen im Englischen verwendet werden. Aus diesem Grund wird empfohlen, Leerzeichen anstelle von Interpunktionszeichen 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 markiert werden.
$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.
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 dieser Parameter 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 verwenden `$skip` 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.
$top	integer	Optional. Die Anzahl der abzurufenden Suchergebnisse. Der Standardwert ist 50. Wenn er mit POST aufgerufen wird, heißt dieser Parameter top anstelle von `$top`. 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 beispiel unten). 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 nicht angeben `$top`. 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.

Antwort

Bei erfolgreicher Antwort wird der Statuscode "200 OK" zurückgegeben.

  {
    "@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),
      "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.

Durchsuchen Sie den Index in absteigender Reihenfolge nach Datum:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

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

Durchsuchen Sie in einer Facettensuche den Index, und rufen Sie Facetten für Kategorien, Bewertungen, Tags und Elemente 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "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 zwischengeschaltete Unterdokumente (Räume), sodass die Antwort die Anzahl der Hotels bestimmt, die zimmer in jedem Preisbucket enthalten.

Wenn Sie einen Filter verwenden, schränken Sie das vorherige Facettenabfrageergebnis ein, 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=2020-06-30

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

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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Durchsuchen Sie den Index innerhalb bestimmter Felder (z. B. in einem Sprachfeld):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

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

Durchsuchen Sie den Index innerhalb mehrerer Felder. Beispiel: Sie können durchsuchbare Felder innerhalb desselben Index in mehreren Sprachen speichern und abfragen. Wenn englische und französische Beschreibungen im selben Dokument vorhanden sind, können Sie in den Abfrageergebnissen alle oder alle zurückgeben:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Sie können nur den Index gleichzeitig abfragen. Erstellen Sie nicht mehrere Indizes für jede Sprache, es sei denn, Sie planen, einzeln abzufragen.

Paging: Ruft die erste Seite von Elementen ab (Seitengröße ist 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

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

Paging: Rufen Sie die zweite Seite von Elementen ab (Seitengröße ist 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

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

Rufen Sie einen speziellen Satz von Feldern ab:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

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

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=2020-06-30

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

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

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

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

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=2020-06-30

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

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=2020-06-30

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

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=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "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.
Suchen Von Dokumenten im Index mithilfe der Lucene-Abfragesyntax). 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=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```

Freigeben über