Azure Cognitive Search Clientbibliothek für Java – Version 11.5.12

  • Artikel

Dies ist die Java-Clientbibliothek für Azure Cognitive Search. Azure Cognitive Search-Dienst ist eine Such-as-a-Service-Cloudlösung, die Entwicklern APIs und Tools zum Hinzufügen einer umfassenden Suchumgebung für private, heterogene Inhalte in Web-, mobilen und Unternehmensanwendungen 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. Wenn sich Ihre Daten bereits in Azure befinden, können Sie einen Indexer erstellen, 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 Cognitive Search 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 (Maven) | API-Referenzdokumentation| Produktdokumentation | Proben

Erste Schritte

Einschließen des Pakets

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-search-documents</artifactId>
    <version>11.5.12</version>
</dependency>

Voraussetzungen

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

Um mit dem Azure Cognitive Search-Dienst zu interagieren, müssen Sie eine instance der Search Client-Klasse erstellen. Um dies zu ermöglichen, benötigen Sie folgendes:

  1. URL-Endpunkt
  2. API-Schlüssel

für Ihren Dienst an. 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>

Hinweis:

  • Der obige Azure CLI-Beispielausschnitt ruft einen Administratorschlüssel ab. Dies ermöglicht einen einfacheren Zugriff beim Untersuchen von APIs, sollte aber sorgfältig verwaltet werden.
  • 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.

Das SDK stellt drei Clients bereit.

  • SearchIndexClient für CRUD-Vorgänge für Indizes und Synonymzuordnungen.
  • SearchIndexerClient für CRUD-Vorgänge für Indexer, Datumsquellen und Skillsets.
  • SearchClient für alle Dokumentvorgänge.

Erstellen eines SearchIndexClient

Zum Erstellen eines SearchIndexClient/SearchIndexAsyncClientbenötigen Sie die Werte des Azure Cognitive Search-Dienst-URL-Endpunkts und des Administratorschlüssels.

SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

oder

SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

Erstellen eines SearchIndexerClient

Zum Erstellen eines SearchIndexerClient/SearchIndexerAsyncClientbenötigen Sie die Werte des Azure Cognitive Search-Dienst-URL-Endpunkts und des Administratorschlüssels.

SearchIndexerClient searchIndexerClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

oder

SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

Erstellen eines SearchClient

Sobald Sie über die Werte des Azure Cognitive Search-Dienst-URL-Endpunkts und des Administratorschlüssels verfügen, können Sie den SearchClient/SearchAsyncClient mit einem vorhandenen Indexnamen erstellen:

SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildClient();

oder

SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildAsyncClient();

Senden Ihrer ersten Suchabfrage

Um mit Azure Cognitive Search ausführen zu können, erstellen Sie zuerst einen Index gemäß dieser Anleitung. Wenn ein Index erstellt wurde, können Sie die folgenden Beispiele verwenden, um mit der Verwendung des SDK zu beginnen.

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 noch nicht in der Suche 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 zwei Standard Clienttypen verfügbar.

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.

Abfragen

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 wie SearchDocument ein Wörterbuch für Suchergebnisse

SearchDocument ist der Standardtyp, der von Abfragen zurückgegeben wird, wenn Sie keinen eigenen angeben. Hier führen wir die Suche durch, führen die Ergebnisse auf und extrahieren Daten mithilfe SearchDocumentdes Wörterbuchindexers.

for (SearchResult searchResult : searchClient.search("luxury")) {
    SearchDocument doc = searchResult.getDocument(SearchDocument.class);
    String id = (String) doc.get("hotelId");
    String name = (String) doc.get("hotelName");
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

Verwenden der Java-Modellklasse für Suchergebnisse

Definieren Sie eine Hotel-Klasse.

public class Hotel {
    private String id;
    private String name;

    public String getId() {
        return id;
    }

    public Hotel setId(String id) {
        this.id = id;
        return this;
    }

    public String getName() {
        return name;
    }

    public Hotel setName(String name) {
        this.name = name;
        return this;
    }
}

Verwenden Sie es anstelle von SearchDocument beim Abfragen.

for (SearchResult searchResult : searchClient.search("luxury")) {
    Hotel doc = searchResult.getDocument(Hotel.class);
    String id = doc.getId();
    String name = doc.getName();
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

Wenn Sie das Schema des Suchindex kennen, empfiehlt es sich, eine Java-Modellklasse zu erstellen.

Suchoptionen

Die SearchOptions bieten eine leistungsstarke Kontrolle über das Verhalten unserer Abfragen.

Suchen wir nach den 5 besten Luxushotels mit einer guten Bewertung.

SearchOptions options = new SearchOptions()
    .setFilter("rating ge 4")
    .setOrderBy("rating desc")
    .setTop(5);
SearchPagedIterable searchResultsIterable = searchClient.search("luxury", options, Context.NONE);
// ...

Erstellen eines Index

Sie können verwenden SearchIndexClient , um einen Suchindex zu erstellen. Indizes können auch Vorschlagser, lexikalische Analysetools und vieles mehr definieren.

Es gibt mehrere Möglichkeiten, Suchfelder für einen Suchindex vorzubereiten. Für grundlegende Anforderungen stellen wir eine statische Hilfsmethode buildSearchFields in SearchIndexClient und SearchIndexAsyncClientbereit, die die Java-POJO-Klasse in List<SearchField>konvertieren kann. Es gibt drei Anmerkungen SimpleFieldProperty, SearchFieldProperty und FieldBuilderIgnore zum Konfigurieren des Felds der Modellklasse.

List<SearchField> searchFields = SearchIndexClient.buildSearchFields(Hotel.class, null);
searchIndexClient.createIndex(new SearchIndex("index", searchFields));

Für erweiterte Szenarien können Wir Suchfelder direkt mit SearchField erstellen.

List<SearchField> searchFieldList = new ArrayList<>();
searchFieldList.add(new SearchField("hotelId", SearchFieldDataType.STRING)
    .setKey(true)
    .setFilterable(true)
    .setSortable(true));

searchFieldList.add(new SearchField("hotelName", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setFilterable(true)
    .setSortable(true));
searchFieldList.add(new SearchField("description", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setAnalyzerName(LexicalAnalyzerName.EU_LUCENE));
searchFieldList.add(new SearchField("tags", SearchFieldDataType.collection(SearchFieldDataType.STRING))
    .setSearchable(true)
    .setFilterable(true)
    .setFacetable(true));
searchFieldList.add(new SearchField("address", SearchFieldDataType.COMPLEX)
    .setFields(new SearchField("streetAddress", SearchFieldDataType.STRING).setSearchable(true),
        new SearchField("city", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("stateProvince", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("country", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("postalCode", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true)
    ));

// Prepare suggester.
SearchSuggester suggester = new SearchSuggester("sg", Collections.singletonList("hotelName"));
// Prepare SearchIndex with index name and search fields.
SearchIndex index = new SearchIndex("hotels").setFields(searchFieldList).setSuggesters(suggester);
// Create an index
searchIndexClient.createIndex(index);

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 hotel = searchClient.getDocument("1", Hotel.class);
System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());

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 = new IndexDocumentsBatch<>();
batch.addUploadActions(Collections.singletonList(new Hotel().setId("783").setName("Upload Inn")));
batch.addMergeActions(Collections.singletonList(new Hotel().setId("12").setName("Renovated Ranch")));
searchClient.indexDocuments(batch);

Die Anforderung wird standardmäßig ausgelöst IndexBatchException , wenn eine der einzelnen Aktionen fehlschlägt, und Sie können verwenden findFailedActionsToRetry , um fehlerhafte Dokumente erneut zu versuchen. Es gibt auch eine throwOnAnyError Option, und Sie können sie auf false festlegen, um eine erfolgreiche Antwort mit einer IndexDocumentsResult zur Überprüfung zu erhalten.

Asynchrone APIs

In den bisherigen Beispielen wurden synchrone APIs verwendet, aber wir bieten auch vollständige Unterstützung für asynchrone APIs. Sie müssen SearchAsyncClient verwenden.

searchAsyncClient.search("luxury")
    .subscribe(result -> {
        Hotel hotel = result.getDocument(Hotel.class);
        System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());
    });

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.
  • Legen Sie in audienceSearchClientBuilder, SearchIndexClientBuilderoder fest. SearchIndexerClientBuilder
// Create a SearchClient that will authenticate through AAD in the China national cloud.
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .indexName(indexName)
    .credential(new DefaultAzureCredentialBuilder()
        .authorityHost(AzureAuthorityHosts.AZURE_CHINA)
        .build())
    .audience(SearchAudience.AZURE_CHINA)
    .buildClient();

Problembehandlung

Allgemein

Wenn Sie mit Azure Cognitive Search mithilfe dieser Java-Clientbibliothek interagieren, entsprechen vom Dienst zurückgegebene Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden. Der Dienst gibt beispielsweise einen 404 Fehler zurück, wenn Sie versuchen, ein Dokument abzurufen, das in Ihrem Index nicht vorhanden ist.

Behandeln von Suchfehlerantworten

Jeder Such-API-Vorgang, der fehlschlägt, löst mit hilfreich Status codesausHttpResponseException. Viele dieser Fehler können wiederhergestellt werden.

try {
    Iterable<SearchResult> results = searchClient.search("hotel");
} catch (HttpResponseException ex) {
    // The exception contains the HTTP status code and the detailed message
    // returned from the search service
    HttpResponse response = ex.getResponse();
    System.out.println("Status Code: " + response.getStatusCode());
    System.out.println("Message: " + ex.getMessage());
}

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.

Aktivieren der Protokollierung

Azure SDKs für Java bieten einen konsistenten Protokollierungsverlauf, um die Problembehandlung von Anwendungsfehlern zu unterstützen und deren Lösung zu beschleunigen. Die erstellten Protokolle erfassen den Flow einer Anwendung, bevor sie den Endzustand erreichen. Dies trägt zur Ermittlung der Grundursache bei. Informationen zum Aktivieren der Protokollierung finden Sie im Protokollierungswiki.

HTTP-Standardclient

Standardmäßig wird ein Netty-basierter HTTP-Client verwendet. Das Wiki für HTTP-Clients enthält weitere Informationen zum Konfigurieren oder Ändern des HTTP-Clients.

Nächste Schritte

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

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