Azure Cognitive Search Clientbibliothek für .NET – Version 11.4.0

  • Artikel

Azure Cognitive Search ist eine Search-as-a-Service-Cloudlösung, die Entwicklern APIs und Tools zum Hinzufügen von umfangreichen Suchfunktionen für private, heterogene Inhalte in Web- und Unternehmensanwendungen sowie in mobilen Anwendungen bietet.

Der Azure Cognitive Search-Dienst eignet sich gut für die folgenden Anwendungsszenarien:

  • Konsolidieren Sie verschiedene Inhaltstypen in einem einzigen durchsuchbaren Index. Um einen Index aufzufüllen, können Sie JSON-Dokumente pushen, die Ihre Inhalte enthalten, oder wenn sich Ihre Daten bereits in Azure befinden, erstellen Sie einen Indexer, um Daten automatisch zu pullen.
  • Fügen Sie Skillsets an einen Indexer an, um durchsuchbare Inhalte aus Bildern und umfangreichen Textdokumenten zu erstellen. Ein Skillset nutzt KI von Cognitive Services für integrierte OCR, Entitätserkennung, Schlüsselbegriffsextraktion, Spracherkennung, Textübersetzung und Stimmungsanalyse. Sie können auch benutzerdefinierte Fähigkeiten hinzufügen, um die externe Verarbeitung Ihrer Inhalte während der Datenerfassung zu integrieren.
  • Implementieren Sie in einer Suchclientanwendung Abfragelogik und Benutzeroberflächen, die kommerziellen Websuchmaschinen ähneln.

Verwenden Sie die Azure.Search.Documents-Clientbibliothek für Folgendes:

  • Übermitteln Sie Abfragen für einfache und erweiterte Abfrageformulare, die Fuzzy-Suche, Feldhaltersuche und reguläre Ausdrücke enthalten.
  • Implementieren Sie gefilterte Abfragen für die Facettennavigation, die Räumliche Suche oder die Eingrenzung von Ergebnissen basierend auf Filterkriterien.
  • Erstellen und Verwalten von Suchindizes
  • Hochladen und Aktualisieren von Dokumenten im Suchindex
  • Erstellen und Verwalten von Indexern, die Daten aus Azure in einen Index abrufen.
  • Erstellen und verwalten Sie Skillsets, die der Datenerfassung KI-Anreicherung hinzufügen.
  • Erstellen und verwalten Sie Analysetools für erweiterte Textanalyse oder mehrsprachige Inhalte.
  • Optimieren Sie Ergebnisse durch Bewertungsprofile, um Geschäftslogik oder Aktualität zu berücksichtigen.

Quellcode | Paket (NuGet) | API-Referenzdokumentation | DOKUMENTATION | ZUR REST-APIProduktdokumentation | Proben

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Cognitive Search-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Search.Documents

Voraussetzungen

Sie benötigen ein Azure-Abonnement und einen Suchdienst , um dieses Paket verwenden zu können.

Zum Erstellen eines neuen Suchdiensts können Sie die Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Hier sehen Sie ein Beispiel für die Verwendung der Azure CLI, um eine kostenlose instance für die ersten Schritte zu erstellen:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Weitere Informationen zu verfügbaren Optionen finden Sie unter Auswählen eines Tarifs .

Authentifizieren des Clients

Für alle Anforderungen an einen Suchdienst wird ein API-Schlüssel benötigt, der speziell für Ihren Dienst generiert wurde. Der API-Schlüssel ist der einzige Mechanismus für die Authentifizierung des Zugriffs auf Ihren Suchdienstendpunkt. Sie können Ihren API-Schlüssel über die Azure-Portal oder über die Azure CLI abrufen:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

Es gibt zwei Arten von Schlüsseln, die für den Zugriff auf Ihren Suchdienst verwendet werden: Administratorschlüssel(Lese-/Schreibzugriff) und Abfrageschlüssel(schreibgeschützt). Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist besonders wichtig, um die Suchobjekte in Ihrem Dienst zu schützen. Verwenden Sie für Abfragen aus einer Client-App immer einen Abfrageschlüssel anstelle eines Administratorschlüssels.

Hinweis: Der obige Azure CLI-Beispielausschnitt ruft einen Administratorschlüssel ab, sodass es einfacher ist, apIs zu erkunden, aber er sollte sorgfältig verwaltet werden.

Wir können den API-Schlüssel verwenden, um einen neuen SearchClientzu erstellen.

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

Um als Abhängigkeit in eine ASP.NET Core-App einzufügenSearchClient, installieren Sie zuerst das Paket Microsoft.Extensions.Azure. Registrieren Sie dann den Client in der Startup.ConfigureServices -Methode:

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });
  
    services.AddControllers();
}

Um den obigen Code zu verwenden, fügen Sie diesen zur Konfiguration hinzu:

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

Sie müssen auch Ihren Ressourcenschlüssel angeben, um den Client zu authentifizieren, aber Sie sollten diese Informationen nicht in die Konfiguration einfügen. Verwenden Sie stattdessen bei der Entwicklung Benutzergeheimnisse. Fügen Sie Folgendes zu secrets.json hinzu:

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

Bei der Ausführung in der Produktion empfiehlt es sich, Umgebungsvariablen zu verwenden:

SEARCH__CREDENTIAL__KEY="..."

Oder verwenden Sie andere sichere Methoden zum Speichern von Geheimnissen wie Azure Key Vault.

Weitere Informationen zur Abhängigkeitsinjektion in ASP.NET Core-Apps finden Sie unter Abhängigkeitsinjektion mit dem Azure SDK für .NET.

Wichtige Begriffe

Ein Azure Cognitive Search-Dienst enthält einen oder mehrere Indizes, die eine dauerhafte Speicherung durchsuchbarer Daten in Form von JSON-Dokumenten ermöglichen. (Wenn Sie bei der Suche ganz neu sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen machen.) Die Azure.Search.Documents-Clientbibliothek macht Vorgänge für diese Ressourcen über drei Standard Clienttypen verfügbar.

Die Azure.Search.Documents Clientbibliothek (v11) ist ein völlig neues Angebot für .NET-Entwickler, die Suchtechnologie in ihren Anwendungen verwenden möchten. Es gibt eine ältere, voll ausgestattete Microsoft.Azure.Search Clientbibliothek (v10) mit vielen ähnlich aussehenden APIs. Achten Sie daher darauf, Beim Erkunden von Onlineressourcen Verwirrung zu vermeiden. Eine gute Faustregel besteht darin, den Namespace using Azure.Search.Documents; zu überprüfen, wenn Sie nach uns suchen.

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch threadsübergreifend.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

In den folgenden Beispielen wird ein einfaches Hotel-Dataset verwendet, das Sie aus dem Azure-Portal in Ihren eigenen Index importieren können. Dies sind nur einige der Grundlagen . Weitere Informationen finden Sie in unseren Beispielen.

Erweiterte Authentifizierung

Abfragen

Beginnen wir mit dem Importieren unserer Namespaces.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;

Anschließend erstellen wir einen SearchClient , um auf den Suchindex unseres Hotels zuzugreifen.

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

Es gibt zwei Möglichkeiten, mit den von einer Suchabfrage zurückgegebenen Daten zu interagieren. Erkunden Sie sie mit einer Suche nach einem "Luxushotel".

Verwenden von C#-Typen für Suchergebnisse

Wir können unsere eigenen C#-Typen mit Attributen aus System.Text.Jsondekorieren:

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

    [JsonPropertyName("HotelName")]
    [SearchableField(IsFilterable = true, IsSortable = true)]
    public string Name { get; set; }
}

Dann verwenden wir sie als Typparameter bei Abfragen, um stark typisierte Suchergebnisse zurückzugeben:

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

Wenn Sie mit einem Suchindex arbeiten und das Schema kennen, wird das Erstellen von C#-Typen empfohlen.

Verwenden wie SearchDocument ein Wörterbuch für Suchergebnisse

Wenn Sie keinen eigenen Typ für Suchergebnisse haben, SearchDocument kann stattdessen verwendet werden. Hier führen wir die Suche durch, führen die Ergebnisse auf und extrahieren Daten mithilfe SearchDocumentdes Wörterbuchindexers.

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");
}

SearchOptions

Die SearchOptions bieten eine leistungsstarke Kontrolle über das Verhalten unserer Abfragen. Suchen wir nach den 5 besten Luxushotels mit einer guten Bewertung.

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

Erstellen eines Index

Sie können den SearchIndexClient verwenden, um einen Suchindex zu erstellen. Felder können in einer Modellklasse mithilfe von FieldBuilder definiert werden. Indizes können auch Vorschläge, lexikalische Analysetools und vieles mehr definieren:

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

In Szenarien, in denen das Modell nicht bekannt ist oder nicht geändert werden kann, können Sie Felder auch explizit mit praktischen SimpleFieldKlassen, SearchableFieldoder ComplexField erstellen:

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

Hinzufügen von Dokumenten zu Ihrem Index

Sie können Upload, Merge, MergeOrUploadund Delete mehrere Dokumente aus einem Index in einer einzelnen Batchanforderung ausführen. Es gibt einige besondere Regeln für die Zusammenführung , die sie beachten sollten.

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

Die Anforderung ist auch dann erfolgreich, wenn eine der einzelnen Aktionen fehlschlägt und zur Überprüfung zurückgibt IndexDocumentsResult . Es gibt auch eine ThrowOnAnyError Option, wenn Sie sich nur um Erfolg oder Misserfolg des gesamten Batches kümmern.

Abrufen eines bestimmten Dokuments aus Ihrem Index

Zusätzlich zum Abfragen von Dokumenten mithilfe von Schlüsselwörtern und optionalen Filtern können Sie ein bestimmtes Dokument aus Ihrem Index abrufen, wenn Sie den Schlüssel bereits kennen. Sie können den Schlüssel z. B. aus einer Abfrage abrufen und weitere Informationen dazu anzeigen oder Ihren Kunden zu diesem Dokument navigieren.

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

Asynchrone APIs

Alle bisherigen Beispiele haben synchrone APIs verwendet, aber wir bieten auch vollständige Unterstützung für asynchrone APIs. In der Regel fügen Sie dem Namen der Methode und await der Methode einfach ein Async Suffix hinzu.

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

Authentifizieren in einer nationalen Cloud

Um sich in einer nationalen Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen an Ihrer Clientkonfiguration vornehmen:

  • Legen Sie in AuthorityHost den Anmeldeinformationsoptionen oder über die Umgebungsvariable AZURE_AUTHORITY_HOST fest.
  • Festlegen von in AudienceSearchClientOptions
// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

Problembehandlung

Jeder Azure.Search.Documents-Vorgang, der fehlschlägt, löst einen RequestFailedException mit hilfreichen Status Codes aus. Viele dieser Fehler können wiederhergestellt werden.

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

Sie können auch einfach die Konsolenprotokollierung aktivieren, wenn Sie ausführliche Informationen zu den von Ihnen an den Dienst gesendeten Anforderungen erhalten möchten.

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Nächste Schritte

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie in unserem CONTRIBUTING.md Suchen .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe