Vorschläge (Azure AI Search-REST-API)

  • Artikel

Eine Vorschlagsanforderung ist eine Suchabfrage, die nach übereinstimmenden Werten in Suggester-fähigen Feldern sucht und Dokumente zurückgibt, die eine Übereinstimmung enthalten. Wenn Sie beispielsweise Vorschläge für ein Stadtfeld aktivieren, führt die Eingabe von "Meer" zu Dokumenten, die "Seattle", "Sea Tac" und "Seaside" (alle tatsächlichen Stadtnamen) für dieses Feld enthalten.

Die Antwort ist ein Inhalt aus einem übereinstimmenden Dokument und dem Dokumentschlüssel. Im Gegensatz zur automatischen Vervollständigung, die einen abgeschlossenen Ausdruck oder Ausdruck zurückgibt, der in einer sekundären Abfrage verwendet wird, gibt diese Anforderung Informationen zurück, die in tatsächliche Dokumente aufgelöst werden. Wenn übereinstimmende Begriffe oder Ausdrücke dokumentübergreifend identisch sind, wird der übereinstimmende Inhalt wiederholt. Um die Struktur der Ergebnisse zu verbessern, sollten Sie den $select Filter verwenden, um zusätzliche Felder zurückzugeben, die mehr Differenzierung und Kontext bieten.

Für Dienstanforderungen ist HTTPS erforderlich. Die Suggest-Anforderung kann mit den METHODEN GET oder POST erstellt werden.

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

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

Im Gegensatz zu einer Anforderung zum Suchen von Dokumenten können Sie einen Vorschlagsaufruf an die Tastatureingabe binden, während ein Suchaufruf möglicherweise an ein Klickereignis gebunden ist.

Wenn sie mit GET aufgerufen wird, darf die Länge der Anforderungs-URL nicht mehr als 8 KB betragen. 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 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.
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. Bei Vorgängen vom Typ Suggestions wird dazu Folgendes benötigt:

  • search
  • $filter
  • 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. Beim Aufrufen von Vorschlägen mithilfe von POST ist keine URL-Codierung erforderlich, oder wenn die Azure AI Search .NET-Clientbibliothek die URL-Codierung für Sie verarbeitet.

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder BESCHREIBUNG
Content-Type Erforderlich. Auf application/json
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:

{  
      "filter": "odata_filter_expression",  
      "fuzzy": true | false (default),  
      "highlightPreTag": "pre_tag",  
      "highlightPostTag": "post_tag",  
      "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "field_name_1, field_name_2, ...",  
      "suggesterName": "suggester_name",  
      "top": # (default 5)  
}

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 Abfrageparameter in der URL angegeben, unabhängig davon, ob Sie die API mit GET oder POST aufrufen.
$filter Zeichenfolge Optional. Ein Ausdruck, der die Dokumente filtert, die für Vorschläge in Betracht gezogen werden. In einem Filter können nur filterbare Felder verwendet werden. Filterausdrücke "search.ismatch" und "search.ismatchscoring*" werden in der AutoVervollständigen-API nicht unterstützt. Wenn dieser Parameter mit POST aufgerufen wird, heißt dieser Parameter filter anstelle von $filter. Ausführliche Informationen zur Teilmenge der von Azure AI Search unterstützten OData-Ausdrucksgrammatik finden Sie unter OData-Ausdruckssyntax für Azure KI Search.
unscharf boolean Optional. Der Standardwert ist „false“. Wenn sie auf true festgelegt ist, findet diese API Vorschläge, auch wenn im Suchtext ein ersetztes oder fehlendes Zeichen vorhanden ist. Der Bearbeitungsabstand beträgt 1 pro Abfragezeichenfolge. Wenn die Abfragezeichenfolge aus mehreren Begriffen besteht, kann nur ein fehlendes, zusätzliches, substituiertes oder transponiertes Zeichen in der gesamten Zeichenfolge vorhanden sein. Das Aktivieren von Fuzzy-Übereinstimmungen kann in einigen Szenarien eine bessere Erfahrung sein. Dies ist mit Leistungskosten verbunden, da Fuzzy-Vorschlagssuchen langsamer sind und mehr Ressourcen verbrauchen.
highlightPostTag Zeichenfolge Optional. Standardmäßig wird eine leere Zeichenfolge verwendet. Ein Zeichenfolgentag, das an den hervorgehobenen 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 #). Wenn sie mithilfe von GET aufgerufen werden, müssen die reservierten Zeichen in der URL prozentual codiert sein (z. B. %23 statt #).
highlightPreTag Zeichenfolge Optional. Standardmäßig wird eine leere Zeichenfolge verwendet. Ein Zeichenfolgentag, das dem hervorgehobenen Begriff vorangestellt wird. Muss mit highlightPostTag festgelegt werden. Wenn sie mithilfe von GET aufgerufen werden, müssen die reservierten Zeichen in der URL prozentual codiert sein (z. B. %23 statt #).
$orderby Zeichenfolge Optional. Eine Liste von Ausdrücken (durch Kommas voneinander getrennt), nach denen die Ergebnisse sortiert werden sollen. Jeder Ausdruck kann ein Feldname oder ein Aufruf der Funktion geo.distance() sein. Jedem Ausdruck kann "asc" (aufsteigend) oder "desc" (absteigend) folgen. Standardmäßig wird in aufsteigender Reihenfolge sortiert. Es gibt einen Grenzwert von 32 Klauseln für $orderby. Wenn dieser Parameter mit POST aufgerufen wird, heißt dieser Parameter order anstelle von $orderby.
minimumCoverage integer Optional. Die Standardwerte sind 80. Eine Zahl zwischen 0 und 100, die den Prozentsatz des Indexes angibt, der zum Verarbeiten der Abfrage verfügbar sein muss, bevor sie als Erfolg gemeldet werden kann.

Der Standardwert spiegelt eine Verzerrung in Bezug auf Geschwindigkeit und Effizienz gegenüber der vollständigen Abdeckung wider. Die Reduzierung der Abdeckung schränkt die Abfrageerweiterung ein, sodass die Ergebnisse schneller zurückkommen können. Außerdem kann die Abfrage bei teilweiser Indexverfügbarkeit erfolgreich sein, auch wenn ein Shard aufgrund von Dienstintegritätsproblemen oder Indexwartungen nur langsam reagiert oder nicht verfügbar ist.

Unabhängig vom Wert von minimumCoverage muss dieser Prozentsatz des Index verfügbar sein, oder Vorschläge gibt HTTP-status Code 503 zurück. Wenn Vorschläge auf minimumCoverage-Ebene erfolgreich sind, wird HTTP 200 zurückgegeben und ein @search.coverage Wert in der Antwort enthalten, der den Prozentsatz des Index angibt, der beim Warten der Abfrage verfügbar war.

Das Senken dieses Werts kann hilfreich sein, wenn Fehler 503 auftreten. Andernfalls könnten Sie erwägen, den Wert zu erhöhen, wenn die Antwort unzureichende Übereinstimmungen liefert.
search Zeichenfolge Erforderlich. Der Suchtext, der zum Vorschlagen von Abfragen verwendet wird. Er muss zwischen 1 und 100 Zeichen lang sein. Es darf keine Operatoren, Abfragesyntax oder Anführungszeichen enthalten.
searchFields Zeichenfolge Optional. Die Liste von Feldnamen (durch Kommas voneinander getrennt), die nach dem angegebenen Suchtext durchsucht werden sollen. Zielfelder müssen in der Suggesters-Definition im Index aufgeführt werden.
$select Zeichenfolge Optional. Eine Liste von Feldern (durch Kommas voneinander getrennt), die abgerufen werden sollen. Wenn nicht angegeben, werden nur der Dokumentschlüssel und der Vorschlagstext zurückgegeben. Sie können alle Felder explizit anfordern, indem Sie diesen Parameter auf *setzen. Beim Aufrufen mit POST heißt dieser Parameter select anstelle von $select.
suggesterName Zeichenfolge Erforderlich. Der Name des Vorschlags, der in der Suggesters-Auflistung angegeben ist, die Teil der Indexdefinition ist. Ein Vorschlag bestimmt, welche Felder auf vorgeschlagene Abfragebegriffe überprüft werden.
$top integer Optional. Standardwert ist 5). Die Anzahl der automatisch abgeschlossenen Vorschläge, die abgerufen werden sollen. Der Wert muss eine Zahl zwischen 1 und 100 sein. Beim Aufrufen mit POST wird dieser Parameter top anstelle von $top genannt.

Antwort

Statuscode: "200 OK" wird für eine erfolgreiche Antwort zurückgegeben.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

Wenn die Projektionsoption zum Abrufen von Feldern verwendet wird, sind sie in jedem Element des Arrays enthalten:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

Beispiele

Abrufen von 5 Vorschlägen, wobei die eingegebene Teilsuchzeichenfolge "Lux" ist:

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

Beachten Sie, dass suggesterName in einem Vorschlagsvorgang erforderlich ist.

Weitere Informationen