Dokumente durchsuchen (Azure Cognitive Search REST-API)

Eine Abfrageanforderung ist auf die Dokumentsammlung eines einzelnen Indexes in einem Suchdienst ausgerichtet. Sie enthält Parameter, die die Übereinstimmungskriterien definieren, sowie Parameter, die die Antwort formen.

Sie können GET oder POST verwenden. Abfrageparameter werden bei GET-Anforderungen in der Abfragezeichenfolge und bei POST-Anforderungen im Anforderungstext angegeben.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]  
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 sehr 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. Obwohl die Größenbeschränkung für POST-Anforderungen sehr hoch ist, dürfen Filterausdrücke nicht übermäßig komplex sein. Weitere Informationen zu Einschränkungen der Filterkomplexität finden Sie unter OData-Ausdruckssyntax für Azure Cognitive Search.

URI-Parameter

Parameter Beschreibung
[Dienstname] Erforderlich. Legen Sie diesen auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
[Indexname]/docs Erforderlich. Gibt die Dokumentsammlung eines benannten Indexes an.
[Abfrageparameter] Abfrageparameter werden im 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.

Empfehlungen zur URL-Codierung

Denken Sie daran, bestimmte Abfrageparameter beim direkten Aufrufen der GET-REST-API url-encode zu codieren. Für einen Vorgang zum Durchsuchen von Dokumenten kann die URL-Codierung für die folgenden Abfrageparameter erforderlich sein:

  • 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. Es ist keine URL-Codierung erforderlich, wenn POST oder die Azure Cognitive Search .NET-Clientbibliothekverwendet wird, die die Codierung für Sie übernimmt.

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder BESCHREIBUNG
Content-Type Erforderlich. Legen Sie diese Einstellung auf "application/json" fest.
api-key Erforderlich. Eine eindeutige, vom System generierte Zeichenfolge, die die Anforderung bei Ihrem Suchdienst authentifiziert. Abfrageanforderungen für die Dokumentsammlung 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 Dokumentsammlung verwendet. Sie finden den API-Schlüssel im Dashboard Ihres Suchdiensts im Azure-Portal.

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 können Azure Cognitive Search nicht alle angeforderten Ergebnisse in einer einzelnen Search-Antwort zurückgeben. Dies kann aus unterschiedlichen Gründen auftreten, z. B. wenn die Abfrage zu viele Dokumente anfordert, indem $top nicht angegeben wird oder ein Wert für $top angegeben wird, der zu groß ist. In solchen Fällen enthält Azure Cognitive Search die @odata.nextLink Anmerkung im Antworttext und auch, wenn es sich um eine @search.nextPageParameters 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. Ausführliche Informationen zur Syntax dieser Anmerkungen und zur Stelle, an der sie im Antworttext angezeigt werden, finden Sie im Beispiel unter Antwort weiter unten.

Die Gründe, warum Azure Cognitive Search Fortsetzungstoken zurückgeben können, sind implementierungsspezifisch und können geändert werden. 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, anstatt einen allgemeinen Mechanismus für 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 $top=10 und $skip=0 aufweisen, die zweite Anforderung sollte $top=1' und $skip=10 aufweisen, 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 wie unten angegeben aufgeführt.

Name Typ BESCHREIBUNG
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 mit GET oder POST durchsuchen aufrufen.
$count boolean Optional. Gültige Werte sind "true" oder "false". Der Standardwert ist "false". Wenn dieser Parameter mit POST aufgerufen wird, erhält er den Namen 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 $top und $skip ignoriert werden. Das Festlegen dieses Werts auf "true" kann die Leistung beeinträchtigen. Die zurückgegebene Anzahl ist eine Näherung. Wenn Sie nur die Anzahl ohne Dokumente abrufen möchten, können Sie $top=0 verwenden.
Facet Zeichenfolge Optional. Ein Feld, nach dem facettiert werden soll. Die Zeichenfolge kann Parameter zum Anpassen des Facetings enthalten, ausgedrückt als durch Trennzeichen getrennte Name-Wert-Paare. Wenn dieser Parameter mit POST aufgerufen wird, wird er als Facets und nicht als Facet bezeichnet.

Gültige Werte sind "count", "sort", "values", "interval" und "timeoffset".

"count" ist die maximale Anzahl von Facetausdrücken. 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 facettierte Feld eine große Anzahl eindeutiger Begriffe enthält. Beispielsweise ruft "facet=category,count:5" die fünf wichtigsten Kategorien in Facettenergebnissen ab. Wenn der count-Parameter kleiner als die Anzahl eindeutiger Begriffe ist, sind die Ergebnisse möglicherweise nicht genau. Dies liegt an der Art, wie Facettenabfragen über Shards hinweg verteilt werden. Eine höhere Anzahl erhöht im Allgemeinen die Genauigkeit der Begriffsanzahl, jedoch zu Leistungskosten.

"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 value, 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 ersten drei Kategorien "Budget", "Motel" und "Luxury" sind und "Budget" 5, "Motel" 6 und "Luxury" 4 Treffer aufweist, werden die Buckets in der Reihenfolge "Motel", "Budget", "Luxury" sortiert. Für -value erzeugt "facet=rating,sort:-value" Buckets für alle möglichen Bewertungen in absteigender Reihenfolge nach Wert (wenn die Bewertungen beispielsweise zwischen 1 und 5 liegen, werden die Buckets 5, 4, 3, 2, 1 sortiert, unabhängig davon, wie viele Dokumente mit jeder Bewertung übereinstimmen).

"values" kann auf numerische Werte mit Pipetrennzeichen oder Edm.DateTimeOffset-Werte festgelegt werden, die einen dynamischen Satz von Faceteintragswerten angeben (z.B. "facet=baseRate,values:10 | 20" erzeugt drei Buckets: einen für die Basisrate 0 bis einschließlich 10, einen für 10 bis einschließlich 20 und einen für 20 und höher). Die Zeichenfolge "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" erzeugt zwei Buckets: einen für Hotels, die vor Februar 2010 zusammengestellt wurden, und einen für Hotels, die den 1. Februar 2010 oder höher besuchen.

"interval" 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 Basisratenbereichen der Größe 100. Wenn die Basispreise alle zwischen 60 und 600 USD 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 zusammengestellt wurden.

"timeoffset" kann auf ([+-]hh:mm, [+-]hhmm oder [+-]hh) festgelegt werden. Bei Verwendung muss der timeoffset-Parameter mit der Interval-Option 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 UHR UTC beginnt (Mitternacht in der Zielzeitzone).

count und sort können in derselben Facetspezifikation kombiniert werden, aber sie können nicht mit Intervallen oder Werten kombiniert werden, und interval und values können nicht kombiniert werden.

Intervallfacetten zur Datumszeit werden basierend auf der UTC-Zeit berechnet, wenn timeoffset nicht angegeben ist. 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 von mit POST wird dieser Parameter filter anstelle von $filter benannt. Ausführliche Informationen zur Teilmenge der OData-Ausdrucksgrammatik, die Azure Cognitive Search unterstützt, finden Sie unter OData-Ausdruckssyntax für Azure Cognitive 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 Trefferhervorhebung verwendet werden. Standardmäßig gibt Azure Cognitive Search bis zu 5 Hervorhebungen pro Feld zurück. Der Grenzwert kann pro Feld konfiguriert werden, indem "-" 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 Feld description 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 markierten Begriff 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 voranzustellen ist. 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 für die Abfrage verfügbar sein muss, bevor sie als erfolgreich gemeldet werden kann. Der Standardwert ist "100".

Eine Abdeckung von 100 Prozent bedeutet, dass alle Shards auf die Anforderung geantwortet haben (weder Dienstzustandsprobleme noch Wartungsaktivitäten reduzierte Abdeckung). Unter der Standardeinstellung gibt die vollständige Abdeckung den HTTP-Statuscode 503 zurück.

Die Verringerung der Mindestanzahl von Wiederherstellen 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 festlegen und die Suche erfolgreich ist, wird HTTP 200 zurückgegeben und ein Wert in die Antwort eingefügt, @search.coverage 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. Wenn die Verfügbarkeit der Suche jedoch wichtiger ist als die Treffersuche, kann die Reduzierung der Abdeckung eine sinnvolle Strategie zur Risikominderung sein.
$orderby Zeichenfolge Optional. Eine Liste von Ausdrücken (durch Kommas voneinander getrennt), nach denen die Ergebnisse sortiert werden sollen. Wenn dieser Parameter mit POST aufgerufen wird, erhält er den Namen orderby anstelle von $orderby. Jeder Ausdruck kann entweder ein Feldname oder ein Aufruf der geo.distance()-Funktion sein. Auf jeden Ausdruck kann "asc" folgen, um aufsteigend anzugeben, und "desc" zum Angeben von absteigend. Wenn das Sortierfeld NULL-Werte enthält, 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 keine $orderby angegeben wird, wird die Standardsortierreihenfolge nach Dokumentabgleichsbewertung absteigend angezeigt. Es gibt einen Grenzwert von 32 Klauseln für $orderby.
queryType Zeichenfolge Optional. Gültige Werte sind "simple" oder "full". Der Standardwert ist „simple“.

"simple" interpretiert Abfragezeichenfolgen mithilfe der einfachen Abfragesyntax, die Symbole wie + , und * "" zulässt. Abfragen werden standardmäßig in allen durchsuchbaren Feldern (oder in searchFields angegebenen Feldern) in jedem Dokument ausgewertet.

"full" interpretiert Abfragezeichenfolgen mithilfe der vollständigen Lucene-Abfragesyntax, die feldspezifische und gewichtete Suchvorgänge ermöglicht. Die Bereichssuche wird in der Lucene-Abfragesprache nicht unterstützt, sondern nur $filter mit ähnlichen Funktionen.
scoringParameter Zeichenfolge Optional. Gibt die Werte für jeden Parameter an, der in einer Bewertungsfunktion (z. B. referencePointParameter) im Format "name-value1,value2,..." definiert ist. Wenn dieser Parameter mit POST aufgerufen wird, erhält er den Namen scoringParameters anstelle von scoringParameter. Außerdem geben Sie es als JSON-Array von Zeichenfolgen an, wobei jede Zeichenfolge ein separates Name-Wert-Paar ist.

Für Bewertungsprofile, die eine Funktion enthalten, trennen Sie die Funktion von ihrer Eingabeliste mit einem - Zeichen. Eine Funktion namens wäre beispielsweise "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 wie für Tagverstärkung, die Kommas enthalten können, können Sie solche Werte in der Liste mit einfachen Anführungszeichen als 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 und möchten die Tagwerte "mytag" "Hello, O'Brien" und "Smith" erhöhen. Die Abfragezeichenfolgenoption wäre dann "&scoringParameter=mytag-'Hello, O''Brien',Smith". Anführungszeichen sind nur für Werte erforderlich, die Kommas enthalten.
scoringProfile 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, z. B. die Dokumenthäufigkeit, global (über alle Shards hinweg) für eine konsistentere Bewertung oder lokal (auf dem aktuellen Shard) für eine geringere Latenz berechnet werden. Weitere Informationen finden Sie unter Bewertungsstatistiken in Azure Cognitive 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 durchsuchbare Felder abfragt werden. 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 findet "search=123.456" einen 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". Die Standardwerte sind "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 werden.
$select Zeichenfolge Optional. Eine Liste von durch Komma getrennten Feldern, die in das Ergebnisset aufgenommen werden. Nur Felder, die als abrufbar markiert sind, können in diese Klausel eingeschlossen werden. Wenn nicht anders angegeben oder auf *gesetzt, werden alle im Schema als abrufbar gekennzeichnete Felder in die Projektion einbezogen. Wenn dieser Parameter mit POST aufgerufen wird, heißt er select anstelle $select.
sessionID Zeichenfolge Optional. Die Verwendung von sessionId hilft, die Konsistenz der Relevanzpunktzahl für Suchdienste mit mehreren Replikaten zu verbessern. Bei Konfigurationen mit mehreren Replikaten können geringfügige Unterschiede zwischen den Relevanzergebnisse einzelner Dokumente für dieselbe Abfrage bestehen. Wenn eine Sitzungs-ID bereitgestellt wird, wird der Dienst nach Möglichkeit eine bestimmte Anforderung an das gleiche Replikat für diese Sitzung weiterverlangen. Seien Sie darauf zurück, dass die wiederholte Erneutverwendung der gleichen Sitzungs-ID-Werte den Lastenausgleich der Anforderungen über Replikate hinweg beeinträchtigen und sich negativ auf die Leistung des Suchdiensts auswirken kann. Der als „sessionId“ verwendete Wert darf nicht mit dem Zeichen „_“ beginnen. Wenn ein Dienst über keine Replikate verfügt, hat dieser Parameter keine Auswirkungen auf die Leistung oder Bewertungskonsistenz.
$skip integer Optional. Die Anzahl der zu überspringenden Suchergebnisse. Wenn dieser Parameter mit POST aufgerufen wird, heißt er skip anstelle $skip. Dieser Wert darf nicht größer als 100.000 sein. Wenn Sie Dokumente nacheinander überprüfen müssen, aber $skip aufgrund dieser Einschränkung nicht verwenden können, sollten Sie stattdessen $orderby für ein Feld mit eindeutigen Werten für jedes Dokument im Index (z. B. den Dokumentschlüssel) und $filter mit einer Bereichsabfrage verwenden.
$top integer Optional. Die Anzahl der abzurufenden Suchergebnisse. Der Standardwert ist 50. Wenn dieser Parameter mit POST aufgerufen wird, wird er als top statt als $top. Wenn Sie einen Wert größer als 1000 angeben und mehr als 1.000 Ergebnisse angezeigt werden, werden nur die ersten 1.000 Ergebnisse zusammen mit einem Link zur nächsten Ergebnisseite zurückgegeben (siehe das folgende @odata.nextLink Beispiel).

Azure Cognitive Search verwendet serverseitiges Paging, um zu verhindern, dass Abfragen zu viele Dokumente gleichzeitig abrufen. Die Standardseitengröße beträgt 50, die maximale Seitengröße 1.000. Dies bedeutet, dass "Dokumente suchen" standardmäßig nur 50 Ergebnisse zurückgibt, wenn Sie keine $top. Wenn mehr als 50 Ergebnisse angezeigt werden, enthält die Antwort Informationen zum Abrufen der nächsten Seite mit mindestens 50 Ergebnissen (siehe " und " " " in den folgenden @odata.nextLink @search.nextPageParameters Beispielen). Wenn Sie einen Wert größer als 1000 für $top angeben und mehr als 1.000 Ergebnisse angezeigt werden, werden nur die ersten 1.000 Ergebnisse zurückgegeben, zusammen mit Informationen zum Abrufen der nächsten Seite mit mindestens 1.000 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 Cognitive Search.

  1. 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"
        }  
    
  2. Durchsuchen Sie in einer Facettensuche den Index, und rufen Sie Facetten nach Kategorien, Bewertungen, Tags und 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=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. Facets zählen das übergeordnete Dokument (Hotels) und keine zwischengeschalteten Unterdokumente (Zimmer), sodass die Antwort die Anzahl der Hotels bestimmt, die in jedem Preisbub Zimmer enthalten.

  3. Geben Sie mithilfe eines Filters das vorherige Facettenabfrageergebnis ein, nachdem der Benutzer Bewertung 3 und 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'"  
        }  
    
  4. 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" ]  
        }  
    
  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"
        }  
    
  6. Durchsuchen Sie den Index innerhalb mehrerer Felder. Beispiel: Sie können durchsuchbare Felder innerhalb desselben Index in mehreren Sprachen speichern und abfragen. Wenn ein Dokument sowohl englische als auch französische Beschreibungen enthält, können Sie die Abfrageergebnisse teilweise oder vollständig 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 den Index nur gleichzeitig abfragen. Erstellen Sie für jede Sprache nur einen Index, es sei denn, Sie fragen bei mehreren Indizes jeden einzeln ab.

  7. Paging: Hier wird die erste Seite mit Elementen (Seitengröße: 10) angezeigt:

    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  
        }  
    
  8. Paging: Hier wird die zweite Seite mit Elementen (Seitengröße: 10) angezeigt:

    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  
        }  
    
  9. 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"
        }  
    
  10. 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'"  
        }  
    
  11. 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"  
        }  
    
  12. 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)')"
        }  
    
  13. Durchsuchen Sie den Index unter der Annahme, dass ein Bewertungsprofil mit der Bezeichnung "geo" mit zwei Funktionen zur Entfernungsbewertung vorhanden ist. Die eine Funktion definiert einen Parameter namens "currentLocation", während die andere einen Parameter namens "lastLocation" definiert:

    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" ]  
        }  
    
  14. 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.

  15. 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"  
    }  
    
  16. 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 versucht, das gleiche Replikat für alle Abfragen innerhalb derselben "Sitzung" als Ziel zu verwenden, 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"
        }  
    

Siehe auch