Freigeben über

Autovervollständigen (Azure AI Search-REST-API)

  • Artikel

Die AutoVervollständigen-API beendet eine teilweise typisierte Abfrageeingabe unter Verwendung vorhandener Begriffe im Suchindex für die Verwendung in einer sekundären Abfrage. Wenn die Abfrageeingabe beispielsweise lautet, gibt "medic"die Autovervollständigen-API , , "medicine" zurück"medicare", "medicaid"wenn diese Begriffe im Index enthalten sind. Intern sucht die Suchmaschine nach übereinstimmenden Begriffen in Feldern, in denen ein Vorschlagsmodul konfiguriert ist.

Für Dienstanforderungen ist HTTPS erforderlich. Die Autovervollständigen-Anforderung kann mithilfe der GET- oder POST-Methoden erstellt werden.

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

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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 der Grenzwert für die POST-Anforderungsgröße sehr 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.
api-version Erforderlich. Eine Liste der unterstützten 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 autovervollständigen kann die URL-Codierung für die folgenden Abfrageparameter erforderlich sein:

  • 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. 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. 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. Abfrageanforderungen für die docs Sammlung können entweder einen Administratorschlüssel oder einen Abfrageschlüssel als api-keyangeben. Der Abfrageschlüssel wird für schreibgeschützte Vorgänge in einer Indexdokumentsammlung verwendet. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung .

Anforderungstext

GET: Keiner

POST:

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "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),
  "search": "partial_search_input",  
  "searchFields": "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-Versionsverwaltung. Für diesen Vorgang wird die api-version als URI-Parameter angegeben, unabhängig davon, ob Sie autovervollständigen mit GET oder POST aufrufen.
Autocompletemode Zeichenfolge Optional. Standardmäßig wird oneTerm verwendet. Gültige Werte sind oneTerm, twoTerms, oneTermWithContext.

oneTerm gibt einen einzelnen Ausdruck zurück. Wenn die Abfrage zwei Begriffe enthält, wird nur der letzte Ausdruck abgeschlossen. Die "washington medic"Antwort kann beispielsweise einen der folgenden einzelnen Begriffe sein: "medicaid", "medicare", . "medicine"

twoTerms stimmt mit zwei Begriffen im Index überein. Die "medic"Antwort kann beispielsweise , oder "medical assistant"sein"medicare coverage". In vielen Fällen werden die einzelnen Begriffe "medicare""medical" oder nicht zurückgegeben, da zwei begriffsbezogene Ausdrücke bevorzugt werden, die übereinstimmen.

oneTermWithContext vervollständigt den letzten Ausdruck in einer Abfrage mit zwei oder mehr Begriffen, wobei die letzten beiden Begriffe ein Ausdruck sind, der im Index vorhanden ist. Die "washington medic"Antwort kann z. B "washington medicaid". sein, "washington medical".
$filter Zeichenfolge Optional. Ein strukturierter Suchausdruck in der OData-Standardsyntax, der die Dokumente filtert, die für die Erstellung der vollständigen Ausdrucksvorschläge berücksichtigt werden. Filterausdrücke "search.ismatch" und "search.ismatchscoring*" werden in der AutoVervollständigen-API nicht unterstützt. 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 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 (1) ein ersetztes oder fehlendes Zeichen vorhanden ist. Dies bietet in einigen Szenarien eine bessere Erfahrung, aber dies hat einen Leistungsaufwand, 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 #).
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 AutoVervollständigen gibt HTTP status Code 503 zurück. Wenn autovervollständigen auf der MinimumCoverage-Ebene erfolgreich ist, wird HTTP 200 zurückgegeben und ein @search.coverage Wert in der Antwort enthalten, der den Prozentsatz des Indexes 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 zu suchende Text. Der zu vervollständigende Suchtext. 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.
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. Die Standardwerte sind 5. Die Anzahl der automatisch abgeschlossenen Vorschläge, die abgerufen werden sollen. Der Wert muss eine Zahl zwischen 1 und 100 sein. Wenn er mit POST aufgerufen wird, wird dieser Parameter top anstelle von $top genannt.

(1) Einschränkungen der Fuzzy bei autovervollständigen:

Erstens ist der Bearbeitungsabstand im Gegensatz zum Fuzzy-Parameter in der Suche auf nur einen Zeichenunterschied pro Token beschränkt. Die Begrenzung des Bearbeitungsabstands auf ein Zeichen bedeutet, dass nicht alle Kandidaten-Übereinstimmungen gefunden werden, aber die Obergrenze ist erforderlich, um ein akzeptables Leistungsniveau zu gewährleisten.

Zweitens erfolgt der Fuzzyschritt nach der partiellen Tokenerweiterung, und nur Begriffe aus demselben Indexshard werden für Fuzzy-Übereinstimmungen berücksichtigt. Diese Einschränkung erhöht die Leistung der Autovervollständigen-API, indem die Aggregation von Fuzzy-Übereinstimmungen über alle Shards beseitigt wird. Diese Einschränkung macht sich weniger bemerkbar, da dem Index mehr Begriffe hinzugefügt werden, was zu einer ähnlichen Begriffsverteilung für jeden Shard führt. Da Begriffe gleichmäßig verteilt sind, sind Fuzzy-Übereinstimmungen innerhalb eines Shards eine gute Annäherung an Fuzzy-Übereinstimmungen im gesamten Index. Die Ergebnisse können jedoch schlechter sein, wenn der Index weniger Begriffe aufweist, z. B. in einem Test- oder Prototypindex, was zu einer ungleichmäßigen Darstellung über Shards führt. Weitere Informationen dazu, wie Indizes in Shards unterteilt werden, finden Sie unter Partitions- und Replikatkombinationen.

Antwort

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

Die Antwortnutzlast weist zwei Eigenschaften auf.

Eigenschaft BESCHREIBUNG
"text" Der abgeschlossene Begriff oder Ausdruck
"queryPlusText" Die anfängliche Abfrageeingabe und der abgeschlossene Ausdruck oder Ausdruck 
{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [
    {
      "text": "...",
      "queryPlusText": "..."
    },
    ...  
  ]
}

Beispiele

Beispiel 1: Rufen Sie drei Vorschläge zur automatischen Vervollständigung ab, bei denen sich die partielle Sucheingabe im Standardmodus (oneTerm) befindet 'washington medic' :

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Antwort:

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Beispiel 2: Abrufen von drei Vorschlägen zur automatischen Vervollständigung, bei denen die partielle Sucheingabe ist 'washington medic' und autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

Antwort:

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

Beachten Sie, dass suggesterName in einem AutoVervollständigen-Vorgang erforderlich ist.

Weitere Informationen