Hinzufügen von Vorschlagsfunktionen zu einem Index für Eingabevorschläge in Azure SearchAdd suggesters to an index for typeahead in Azure Search

EineVorschlagsfunktion ist ein Konstrukt in einem Azure Search-Index, das eine „Vorschläge während der Eingabe“-Umgebung unterstützt.A suggester is a construct in an Azure Search index that supports a "search-as-you-type" experience. Sie enthält eine Liste der Felder, für die Sie Eingabevorschläge für die Abfrage aktivieren möchten.It contains a list of fields for which you want to enable typeahead query inputs. In einem Index unterstützt dieselbe Vorschlagsfunktion diese beiden Varianten von Eingabevorschlägen: AutoVervollständigen vervollständigt den Begriff oder Ausdruck, den Sie eingeben, Vorschläge liefert eine kurze Liste von Ergebnissen.Within an index, the same suggester supports either or both of these two typeahead variants: autocomplete completes the term or phrase you are typing, suggestions provides a short list of results.

Der folgende Screenshot veranschaulicht diese beiden Features für Eingabevorschläge.The following screenshot illustrates both typeahead features. Auf dieser Xbox-Suchseite führen die AutoVervollständigen-Elemente Sie zu einer neuen Suchergebnisseite für die Abfrage, während die Vorschläge tatsächliche Ergebnisse sind, über die Sie zu einer Seite für das entsprechende Spiel gelangen.In this Xbox search page, the autocomplete items take you to a new search results page for that query, whereas the suggestions are actual results that take you to a page for that particular game. Sie können AutoVervollständigen auf ein Element in einer Suchleiste beschränken oder eine Liste wie die hier gezeigte bereitstellen.You can limit autocomplete to one item in a search bar or provide a list like the one shown here. Für Vorschläge können Sie jeden Bereich eines Dokuments anzeigen, der das Ergebnis am besten beschreibt.For suggestions, you can surface any part of a document that best describes the result.

Visueller Vergleich von automatisch vervollständigten Abfragen und Vorschlägen für AbfragenVisual comparison of autocomplete and suggested queries

Um dieses Verhalten in Azure Search zu implementieren, gibt es eine Index- und eine Abfragekomponente.To implement these behaviors in Azure Search, there is an index and query component.

  • Bei der Indexkomponente handelt es sich um eine Vorschlagsfunktion.The index component is a suggester. Sie können das Portal, eine REST-API oder das .NET SDK verwenden, um eine Vorschlagsfunktion zu erstellen.You can use the portal, REST API, or .NET SDK to create a suggester.

  • Die Abfragekomponente ist eine in der Abfrageanforderung angegebene Aktion (entweder ein Vorschlag oder eine AutoVervollständigen-Aktion).The query component is an action specified on the query request (either a suggestion or autocomplete action).

Die „Search-as-you-Type“-Unterstützung (Vorschläge bei der Eingabe) wird auf Feldebene aktiviert.Search-as-you-type support is enabled on a per-field basis. Sie können beide Verhaltensweisen für Eingabevorschläge in derselben Suchlösung implementieren, wenn Sie ein ähnliches Erlebnis wie im Screenshot wünschen.You can implement both typeahead behaviors within the same search solution if you want an experience similar to the one indicated in the screenshot. Beide Anforderungen zielen auf die Dokumentensammlung eines bestimmten Index ab, und die Antworten werden zurückgegeben, nachdem ein Benutzer eine Zeichenfolge aus mindestens 3 Zeichen eingegeben hat.Both requests target the documents collection of specific index and responses are returned after a user has provided at least a three character input string.

Erstellen einer VorschlagsfunktionCreate a suggester

Eine Vorschlagsfunktion verfügt zwar über mehrere Eigenschaften, in erster Linie handelt es sich aber um eine Sammlung von Feldern, für die Sie die Umgebung für Eingabevorschläge aktivieren.Although a suggester has several properties, it is primarily a collection of fields for which you are enabling a typeahead experience. In einer Reise-App können Eingabevorschläge beispielsweise für die Suche nach Zielen, Städten und Attraktionen aktiviert sein.For example, a travel app might want to enable typeahead search on destinations, cities, and attractions. Somit würden alle drei Felder in die Feldsammlung aufgenommen.As such, all three fields would go in the fields collection.

Um eine Vorschlagsfunktion zu erstellen, fügen Sie sie zu einem Indexschema hinzu.To create a suggester, add one to an index schema. Sie können eine Vorschlagsfunktion in einem Index verwenden (nämlich eine Vorschlagsfunktion in der Sammlung der Vorschlagsfunktionen).You can have one suggester in an index (specifically, one suggester in the suggesters collection).

Verwenden der REST-APIUse the REST API

In der REST-API können Sie Vorschlagsfunktionen über Index erstellen oder Index aktualisieren hinzufügen.In the REST API, you can add suggesters through Create Index or Update Index.

{
  "name": "hotels",
  "fields": [
    . . .
  ],
  "suggesters": [
    {
      "name": "sg",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["hotelName", "category"]
    }
  ],
  "scoringProfiles": [
    . . .
  ]
}

Nachdem eine Vorschlagsfunktion erstellt wurde, fügen Sie die Vorschlags-API oder die AutoVervollständigen-API zu Ihrer Abfragelogik hinzu, um das Feature aufzurufen.After a suggester is created, add the Suggestions API or Autocomplete API in your query logic to invoke the feature.

Verwenden des .NET SDKUse the .NET SDK

Definieren Sie in C# ein Suggester-Objekt.In C#, define a Suggester object. Suggesters ist eine Sammlung, aber sie kann nur ein Element enthalten.Suggesters is a collection but it can only take one item.

private static void CreateHotelsIndex(SearchServiceClient serviceClient)
{
    var definition = new Index()
    {
        Name = "hotels",
        Fields = FieldBuilder.BuildForType<Hotel>(),
        Suggesters = new List<Suggester>() {new Suggester()
            {
                Name = "sg",
                SourceFields = new string[] { "HotelId", "Category" }
            }}
    };

    serviceClient.Indexes.Create(definition);

}

EigenschaftsverweisProperty reference

Bei Vorschlagsfunktionen ist zu beachten, dass ein Name (Vorschlagsfunktion werden in einer Anforderung anhand des Namens referenziert), ein Suchmodus („SearchMode“, derzeit nur ein einziger verfügbar: „analyzingInfixMatching“) und die Liste der Felder, für die Eingabevorschläge aktiviert sind, vorhanden sein muss.Key points to notice about suggesters is that there is a name (suggesters are referenced by name on a request), a searchMode (currently just one, "analyzingInfixMatching"), and the list of fields for which typeahead is enabled.

Zu den Eigenschaften, mit denen ein Vorschlag definiert wird, zählen unter anderem:Properties that define a suggester include the following:

EigenschaftProperty BESCHREIBUNGDescription
name Der Name der Vorschlagsfunktion.The name of the suggester. Sie verwenden den Namen der Vorschlagsfunktion beim Aufrufen der Vorschläge-REST-API oder AutoVervollständigen-REST-API.You use the name of the suggester when calling the Suggestions REST API or Autocomplete REST API.
searchMode Die Strategie, mit der nach möglichen Ausdrücken gesucht wird.The strategy used to search for candidate phrases. Derzeit wird nur der Modus analyzingInfixMatching unterstützt. Darin werden Ausdrücke am Anfang oder in der Mitte von Sätzen flexibel verglichen.The only mode currently supported is analyzingInfixMatching, which performs flexible matching of phrases at the beginning or in the middle of sentences.
sourceFields Eine Liste mit einem oder mehreren Feldern, die als Quelle für den Inhalt von Vorschlägen dienen.A list of one or more fields that are the source of the content for suggestions. Als Vorschlagsquellen sind nur Felder vom Typ Edm.String und Collection(Edm.String) zulässig.Only fields of type Edm.String and Collection(Edm.String) may be sources for suggestions. Es können nur Felder ohne benutzerdefinierte Sprachanalyse verwendet werden.Only fields that don't have a custom language analyzer set can be used.

Geben Sie nur die Felder an, die sich für eine erwartete und angemessene Antwort eignen, sei es eine vollständige Zeichenfolge in einer Suchleiste oder eine Dropdownliste.Specify only those fields that lend themselves to an expected and appropriate response, whether it's a completed string in a search bar or a dropdown list.

Ein Hotelname ist ein guter Kandidat, weil er präzise ist.A hotel name is a good candidate because it has precision. Ausführliche Felder wie Beschreibungen und Kommentare sind zu informationsreich.Verbose fields like descriptions and comments are too dense. Sich wiederholende Felder wie Kategorien und Tags sind ebenso weniger effektiv.Similarly, repetitive fields, such as categories and tags, are less effective. In den Beispielen schließen wir ohnehin „category“ ein, um zu zeigen, dass Sie mehrere Felder einbeziehen können.In the examples, we include "category" anyway to demonstrate that you can include multiple fields.

Analyse von SourceFields in einer VorschlagsfunktionAnalysis of SourceFields in a suggester

Azure Search analysiert den Feldinhalt, um das Abfragen einzelner Begriffe zu ermöglichen.Azure Search analyzes the field content to enable querying on individual terms. Für Vorschlagsfunktionen müssen Präfixe zusätzlich zu vollständigen Begriffen indiziert werden. Hierfür ist eine zusätzliche Analyse der Quellfelder erforderlich.Suggesters require prefixes to be indexed in addition to complete terms, which requires additional analysis over the source fields. In benutzerdefinierten Analysetoolkonfigurationen können die verschiedenen Tokenizer und Filter kombiniert werden. Häufig kommt es hierbei zu Kombinationen, die das Erstellen der für die Vorschläge benötigten Präfixe unmöglich machen.Custom analyzer configurations can combine any of the various tokenizers and filters, often in ways that would make producing the prefixes required for suggestions impossible. Aus diesem Grund verhindert Azure Search, dass Felder mit benutzerdefinierten Analysetools in eine Vorschlagsfunktion eingebunden werden.For this reason, Azure Search prevents fields with custom analyzers from being included in a suggester.

Hinweis

Die empfohlene Vorgehensweise zur Umgehung der obigen Einschränkung ist die Verwendung von zwei separaten Feldern für denselben Inhalt.The recommended approach to work around the above limitation is to use 2 separate fields for the same content. Eines der Felder kann so über Vorschlagsfunktionen verfügen, und das andere kann mit einer benutzerdefinierten Analysetoolkonfiguration eingerichtet werden.This will allow one of the fields to have suggesters and the other can be set up with a custom analyzer configuration.

Wann wird eine Vorschlagsfunktion erstellt?When to create a suggester

Um das Neuerstellen eines Index zu vermieden, müssen gleichzeitig eine Vorschlagsfunktion und die in sourceFields angegebenen Felder erstellt werden.To avoid an index rebuild, a suggester and the fields specified in sourceFields must be created at the same time.

Wenn Sie eine Vorschlagsfunktion zu einem bestehenden Index hinzufügen, in dem bestehende Felder in sourceFields enthalten sind, ändert sich die Felddefinition grundlegend und eine Neuerstellung ist erforderlich.If you add a suggester to an existing index, where existing fields are included in sourceFields, the field definition fundamentally changes and a rebuild is required. Weitere Informationen finden Sie unter Neuerstellen eines Azure Search-Indexes.For more information, see How to rebuild an Azure Search index.

Wie wird eine Vorschlagsfunktion verwendet?How to use a suggester

Wie zuvor erwähnt, können Sie eine Vorschlagsfunktion für Vorschläge, AutoVervollständigen oder beides verwenden.As previously noted, you can use a suggester for suggested queries, autocomplete, or both.

Eine Vorschlagsfunktion wird in einer Anforderung zusammen mit dem Vorgang referenziert.A suggester is referenced on the request along with the operation. Geben Sie beispielsweise in einem GET-REST-Aufruf entweder suggest oder autocomplete für die Dokumentensammlung an.For example, on a GET REST call, specify either suggest or autocomplete on the documents collection. Für REST: Nachdem eine Vorschlagsfunktion erstellt wurde, verwenden Sie die Vorschlags-API oder die AutoVervollständigen-API in Ihrer Abfragelogik.For REST, after a suggester is created, use the Suggestions API or the Autocomplete API in your query logic.

Für .NET verwenden Sie SuggestWithHttpMessagesAsync oder AutocompleteWithHttpMessagesAsync.For .NET, use SuggestWithHttpMessagesAsync or AutocompleteWithHttpMessagesAsync.

Ein Beispiel, das beide Anforderungen veranschaulicht, finden Sie unter Beispiel für das Hinzufügen von AutoVervollständigen und Vorschlägen in Azure Search.For an example demonstrating both requests, see Example for adding autocomplete and suggestions in Azure Search.

BeispielcodeSample code

Das Beispiel DotNetHowToAutocomplete enthält sowohl C#- als auch Java-Code und veranschaulicht ein Vorschlagsfunktionskonstrukt, vorgeschlagene Abfragen, AutoVervollständigen und Facet-Navigation.The DotNetHowToAutocomplete sample contains both C# and Java code, and demonstrates a suggester construction, suggested queries, autocomplete, and facet navigation.

Es werden ein Azure Search-Sandboxdienst und ein vorinstallierter Index verwendet, sodass Sie lediglich F5 zum Ausführen drücken müssen.It uses a sandbox Azure Search service and a pre-loaded index so all you have to do is press F5 to run it. Es ist weder ein Abonnement noch eine Anmeldung erforderlich.No subscription or sign in necessary.

Nächste SchritteNext steps

Wir empfehlen, das folgende Beispiel anzuschauen, um zu verstehen, wie die Anforderungen formuliert werden.We recommend the following example to see how the requests are formulated.