bibliothèque cliente Recherche cognitive Azure pour Java - version 11.5.12

  • Article

Il s’agit de la bibliothèque cliente Java pour Recherche cognitive Azure. Recherche cognitive Azure service est une solution cloud de recherche en tant que service qui fournit aux développeurs des API et des outils permettant d’ajouter une expérience de recherche riche sur du contenu privé et hétérogène dans les applications web, mobiles et d’entreprise.

Le service Recherche cognitive Azure convient parfaitement aux scénarios d’application suivants :

  • Regroupez des types de contenu variés dans un index unique pouvant faire l’objet d’une recherche. Pour remplir un index, vous pouvez envoyer (push) des documents JSON qui contiennent votre contenu ou, si vos données se trouvent déjà dans Azure, créer un indexeur pour extraire automatiquement les données.

  • Joignez des ensembles de compétences à un indexeur pour créer du contenu pouvant faire l’objet d’une recherche à partir d’images et de documents texte volumineux. Un ensemble de compétences tire parti de l’IA de Cognitive Services pour l’OCR intégré, la reconnaissance d’entités, l’extraction d’expressions clés, la détection de langue, la traduction de texte et l’analyse des sentiments. Vous pouvez également ajouter des compétences personnalisées pour intégrer le traitement externe de votre contenu pendant l’ingestion de données.

  • Dans une application cliente de recherche, implémentez une logique de requête et des expériences utilisateur similaires aux moteurs de recherche web commerciaux.

Utilisez la bibliothèque cliente Recherche cognitive Azure pour :

  • Envoyez des requêtes pour les formulaires de requête simples et avancés qui incluent la recherche approximative, la recherche générique et les expressions régulières.
  • Implémentez des requêtes filtrées pour la navigation à facettes, la recherche géospatiale ou pour affiner les résultats en fonction de critères de filtre.
  • Créez et gérez des index de recherche.
  • Chargez et mettez à jour des documents dans l’index de recherche.
  • Créez et gérez des indexeurs qui extrayent des données d’Azure dans un index.
  • Créez et gérez des ensembles de compétences qui ajoutent l’enrichissement par IA à l’ingestion de données.
  • Créez et gérez des analyseurs pour l’analyse de texte avancée ou le contenu multilingue.
  • Optimisez les résultats grâce à des profils de scoring pour prendre en compte la logique métier ou la fraîcheur.

| Code sourcePackage (Maven) | Documentation de référence sur les| API | Documentation produitÉchantillons

Prise en main

Inclure le package

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

Prérequis

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

Pour plus d’informations sur les options disponibles, consultez Choisir un niveau tarifaire .

Authentifier le client

Pour interagir avec le service Recherche cognitive Azure, vous devez créer un instance de la classe Search Client. Pour rendre cela possible, vous aurez besoin,

  1. Point de terminaison de l’URL
  2. Clé API

pour votre service. La clé api est le seul mécanisme d’authentification de l’accès à votre point de terminaison de service de recherche. Vous pouvez obtenir votre clé API à partir du Portail Azure ou via Azure CLI :

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

Remarque :

  • L’exemple d’extrait de code Azure CLI ci-dessus récupère une clé d’administration. Cela permet un accès plus facile lors de l’exploration des API, mais il doit être géré avec soin.
  • Il existe deux types de clés utilisées pour accéder à votre service de recherche : les clés d’administration(lecture-écriture) et les clés de requête(lecture seule). Il est essentiel de restreindre l'accès et les opérations dans les applications clientes afin de protéger les ressources de recherche de votre service. Utilisez toujours une clé de requête plutôt qu'une clé d'administration pour toutes les requêtes provenant d'une application cliente.

Le Kit de développement logiciel (SDK) fournit trois clients.

  • SearchIndexClient pour les opérations CRUD sur les index et les mappages de synonymes.
  • SearchIndexerClient pour les opérations CRUD sur les indexeurs, les sources de dates et les ensembles de compétences.
  • SearchClient pour toutes les opérations de document.

Créer un SearchIndexClient

Pour créer un SearchIndexClient/SearchIndexAsyncClient, vous aurez besoin des valeurs du point de terminaison d’URL de service Recherche cognitive Azure et de la clé d’administration.

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

ou

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

Créer un SearchIndexerClient

Pour créer un SearchIndexerClient/SearchIndexerAsyncClient, vous aurez besoin des valeurs du point de terminaison d’URL de service Recherche cognitive Azure et de la clé d’administration.

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

ou

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

Créer un SearchClient

Une fois que vous avez les valeurs du point de terminaison et de la clé d’administration de l’URL du service Recherche cognitive Azure, vous pouvez créer le SearchClient/SearchAsyncClient avec un nom d’index existant :

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

ou

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

Envoyer votre première requête de recherche

Pour exécuter avec Recherche cognitive Azure commencez par créer un index en suivant ce guide. Avec un index créé, vous pouvez utiliser les exemples suivants pour commencer à utiliser le Kit de développement logiciel (SDK).

Concepts clés

Un service Recherche cognitive Azure contient un ou plusieurs index qui fournissent un stockage persistant des données pouvant faire l’objet d’une recherche sous forme de documents JSON. (Si vous débutez dans la recherche, vous pouvez faire une analogie très approximative entre les index et les tables de base de données.) La azure-search-documents bibliothèque cliente expose les opérations sur ces ressources via deux types de clients main.

Exemples

Les exemples suivants utilisent tous un jeu de données Hotel simple que vous pouvez importer dans votre propre index à partir du Portail Azure. Ce ne sont que quelques-unes des bases - s’il vous plaît case activée nos exemples pour bien plus.

Interrogation

Il existe deux façons d’interagir avec les données retournées à partir d’une requête de recherche.

Explorons-les à la recherche d’un hôtel de luxe.

Utiliser SearchDocument comme un dictionnaire pour les résultats de recherche

SearchDocument est le type par défaut retourné par les requêtes lorsque vous ne fournissez pas les vôtres. Ici, nous effectuons la recherche, énumérons les résultats et extrayons les données à l’aide SearchDocumentde l’indexeur de dictionnaire.

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);
}

Utiliser la classe de modèle Java pour les résultats de recherche

Définissez une classe Hotel.

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;
    }
}

Utilisez-le à la place de lors de SearchDocument l’interrogation.

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);
}

Il est recommandé, lorsque vous connaissez le schéma de l’index de recherche, de créer une classe de modèle Java.

Options recherche

Fournissent SearchOptions un contrôle puissant sur le comportement de nos requêtes.

Nous allons rechercher les 5 meilleurs hôtels de luxe avec une bonne note.

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

Création d'un index

Vous pouvez utiliser pour SearchIndexClient créer un index de recherche. Les index peuvent également définir des suggesteurs, des analyseurs lexicales, etc.

Il existe plusieurs façons de préparer des champs de recherche pour un index de recherche. Pour les besoins de base, nous fournissons une méthode buildSearchFields d’assistance statique dans SearchIndexClient et SearchIndexAsyncClient, qui peut convertir la classe Java POJO en List<SearchField>. Il existe trois annotations SimpleFieldPropertyet SearchFieldPropertyFieldBuilderIgnore pour configurer le champ de la classe de modèle.

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

Pour les scénarios avancés, nous pouvons créer des champs de recherche directement à l’aide SearchField de .

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);

Récupération d’un document spécifique à partir de votre index

En plus d’interroger des documents à l’aide de mots clés et de filtres facultatifs, vous pouvez récupérer un document spécifique à partir de votre index si vous connaissez déjà la clé. Vous pouvez obtenir la clé à partir d’une requête, par exemple, et vouloir afficher plus d’informations à son sujet ou naviguer vers ce document.

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());

Ajout de documents à votre index

Vous pouvez Upload, Merge, MergeOrUploadet Delete plusieurs documents à partir d’un index dans une seule requête par lot. Il existe quelques règles particulières à connaître pour la fusion .

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);

La demande est levée IndexBatchException par défaut si l’une des actions individuelles échoue, et vous pouvez utiliser findFailedActionsToRetry pour réessayer sur les documents ayant échoué. Il existe également une throwOnAnyError option, et vous pouvez la définir sur false pour obtenir une réponse réussie avec un IndexDocumentsResult pour inspection.

API asynchrones

Jusqu’à présent, les exemples utilisent des API synchrones, mais nous fournissons également une prise en charge complète des API asynchrones. Vous devez utiliser SearchAsyncClient.

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());
    });

S’authentifier dans un cloud national

Pour vous authentifier dans un cloud national, vous devez effectuer les ajouts suivants à votre configuration client :

  • Définir dans AuthorityHost les options d’informations d’identification ou via la variable d’environnement AZURE_AUTHORITY_HOST
  • Définissez dans audienceSearchClientBuilder, SearchIndexClientBuilderou 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();

Dépannage

Général

Lorsque vous interagissez avec Recherche cognitive Azure à l’aide de cette bibliothèque cliente Java, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les requêtes d’API REST. Par exemple, le service retourne une 404 erreur si vous essayez de récupérer un document qui n’existe pas dans votre index.

Gestion de la réponse d’erreur de recherche

Toute opération d’API de recherche qui échoue lève un HttpResponseException avec utile Status codes. La plupart de ces erreurs peuvent être récupérées.

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());
}

Vous pouvez également activer la journalisation de la console facilement si vous souhaitez approfondir les requêtes que vous formulez sur le service.

Activation de la journalisation

Les kits SDK Azure pour Java fournissent un article de journalisation cohérent pour faciliter la résolution des erreurs d’application et accélérer leur résolution. Les journaux produits capturent le flux d’une application avant d’atteindre l’état terminal pour faciliter la localisation du problème racine. Consultez le wiki de journalisation pour obtenir des conseils sur l’activation de la journalisation.

Client HTTP par défaut

Par défaut, un client HTTP basé sur Netty est utilisé. Le wiki des clients HTTP fournit plus d’informations sur la configuration ou la modification du client HTTP.

Étapes suivantes

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions