Exemple d'envoi - OpenSearch - Centre de documentation Alibaba Cloud

Cette rubrique explique comment envoyer des documents vers une application OpenSearch à l'aide du SDK OpenSearch pour Java V3.1. L'exemple illustre les opérations ADD (ajout), UPDATE (mise à jour) et DELETE (suppression) dans un seul envoi par lot, suivi d'une requête de recherche pour vérifier les résultats.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Une application OpenSearch avec au moins une table configurée
L'ID AccessKey et le secret AccessKey d'un utilisateur Resource Access Management (RAM) disposant des autorisations nécessaires accordées au rôle AliyunServiceRoleForOpenSearch. Pour plus de détails sur le rôle, consultez la page AliyunServiceRoleForOpenSearch. Pour plus de détails sur les permissions, consultez la page Règles d'autorisation d'accès
Le SDK OpenSearch pour Java V3.1 ajouté à votre projet

Important

Utilisez la paire AccessKey d'un utilisateur RAM plutôt que celle de votre compte Alibaba Cloud. La paire AccessKey au niveau du compte accorde l'accès à toutes les opérations API et présente un risque de sécurité plus élevé. Pour créer un utilisateur RAM, consultez la page Créer un utilisateur RAM. Pour créer une paire AccessKey, consultez la page Créer une paire AccessKey.

Configurer les identifiants

Stockez votre paire AccessKey en tant que variables d'environnement. Cela permet de garder les identifiants hors de votre code source.

Linux et macOS

export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>

Remplacez <access_key_id> et <access_key_secret> par l'ID AccessKey et le secret AccessKey de votre utilisateur RAM.

Windows

Créez un fichier de variable d'environnement et ajoutez-y ALIBABA_CLOUD_ACCESS_KEY_ID et ALIBABA_CLOUD_ACCESS_KEY_SECRET, en définissant chacun sur la valeur correspondante.
Redémarrez Windows pour que les modifications prennent effet.

Fonctionnement

Le workflow d'envoi suit trois étapes :

Construisez chaque document sous la forme d'un objet Map contenant les valeurs des champs, puis encapsulez-le dans un objet JSONObject avec une commande (ADD ou DELETE).
Regroupez toutes les entrées JSONObject dans un objet JSONArray, puis appelez documentClient.push() pour soumettre le lot à l'application.
Après l'envoi, exécutez une requête de recherche à l'aide de SearcherClient pour vérifier que les documents apparaissent dans les résultats.

Vous ne pouvez envoyer que des champs appartenant à la même table dans un seul appel d'envoi. L'envoi de champs provenant de différentes tables dans un seul appel n'est pas pris en charge.

Contraintes et format des données

Les jeux de données doivent être dans un format valide. Pour télécharger un exemple de fichier servant de modèle, connectez-vous à la console OpenSearch, accédez à la page Instance Management, trouvez votre application et choisissez More > Upload File dans la colonne Actions.
Construisez les documents directement à l'aide d'objets JSONObject et JSONArray, comme indiqué dans l'exemple ci-dessous.
Si le nombre de documents dans un seul envoi dépasse la limite, l'envoi échoue avec une erreur.
Les applications standard prennent en charge la commande ADD pour ajouter et remplacer entièrement des documents. La commande UPDATE (mise à jour partielle des champs) est uniquement prise en charge par les applications avancées.

Envoyer et interroger des documents

L'exemple suivant envoie quatre documents en un seul appel : ajout de deux documents (doc1, doc2), mise à jour d'un document (doc2 remplacé par doc3) et suppression d'un document (doc1), puis effectue une requête par clé primaire pour vérifier les résultats.

package com.aliyun.opensearch;

import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Lists;
import com.aliyun.opensearch.sdk.dependencies.com.google.common.collect.Maps;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONArray;
import com.aliyun.opensearch.sdk.dependencies.org.json.JSONObject;
import com.aliyun.opensearch.sdk.generated.OpenSearch;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchClientException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchException;
import com.aliyun.opensearch.sdk.generated.commons.OpenSearchResult;
import com.aliyun.opensearch.sdk.generated.document.Command;
import com.aliyun.opensearch.sdk.generated.document.DocumentConstants;
import com.aliyun.opensearch.sdk.generated.search.*;
import com.aliyun.opensearch.sdk.generated.search.general.SearchResult;

import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
import java.util.Map;
import java.util.Random;

public class testPushSearch2 {

    private String appName = "Name of the OpenSearch application that you want to manage"; // (1)
    private String tableName = "Name of the table to which data is to be uploaded";          // (2)
    private String host = "Endpoint of the OpenSearch API in your region";                  // (3)

    public static void main(String[] args) {

        // Read credentials from environment variables                                       // (4)
        String accesskey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String secret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

        System.out.println(String.format("file.encoding: %s", System.getProperty("file.encoding")));
        System.out.println(String.format("defaultCharset: %s", Charset.defaultCharset().name()));

        // ---- Build documents ----

        // Generate random primary key values for doc1 and doc2                              // (5)
        Random rand = new Random();
        int value1 = rand.nextInt(Integer.MAX_VALUE);
        int value2 = rand.nextInt(Integer.MAX_VALUE);

        // doc1: ADD — adds a new document                                                   // (6)
        Map<String, Object> doc1 = Maps.newLinkedHashMap();
        doc1.put("id", value1);

        String title_string = "Upload doc1 in push mode";// UTF-8.
        byte[] bytes;
        try {
            bytes = title_string.getBytes("utf-8");
            String utf8_string = new String(bytes, "utf-8");
            doc1.put("name", utf8_string);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc1.put("phone", "137****1111");

        int[] int_arr = {11,11};
        doc1.put("int_arr", int_arr);

        String[] literal_arr1 = {"Upload doc1 in push mode","Test uploading doc1 in push mode"};
        doc1.put("literal_arr", literal_arr1);

        float[] float_arr = {(float)1.1,(float)1.1};
        doc1.put("float_arr", float_arr);

        doc1.put("cate_id", 1);

        // Standard applications use ADD for both adding and fully replacing documents.      // (7)
        // UPDATE (partial field update) is not supported for standard applications.
        JSONObject json1 = new JSONObject();
        json1.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json1.put(DocumentConstants.DOC_KEY_FIELDS, doc1);

        // doc2: ADD — adds a new document                                                   // (8)
        Map<String, Object> doc2 = Maps.newLinkedHashMap();
        doc2.put("id", value2);

        String title_string2 = "Upload doc2 in push mode";// UTF-8.
        byte[] bytes2;
        try {
            bytes2 = title_string2.getBytes("utf-8");
            String utf8_string2 = new String(bytes2, "utf-8");
            doc2.put("name", utf8_string2);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc2.put("phone", "137****2222");

        int[] int_arr2 = {22,22};
        doc2.put("int_arr", int_arr2);

        String[] literal_arr2 = {"Upload doc2 in push mode","Test uploading doc2 in push mode"};
        doc2.put("literal_arr", literal_arr2);

        float[] float_arr2 = {(float)2.2,(float)2.2};
        doc2.put("float_arr", float_arr2);

        doc2.put("cate_id", 1);

        JSONObject json2 = new JSONObject();
        json2.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json2.put(DocumentConstants.DOC_KEY_FIELDS, doc2);

        // doc3: ADD with doc2's primary key — replaces doc2 with doc3's field values        // (9)
        Map<String, Object> doc3 = Maps.newLinkedHashMap();
        doc3.put("id", value2);   // same primary key as doc2

        String title_string3 = "Update doc2 to doc3 in push mode";// UTF-8.
        byte[] bytes3;
        try {
            bytes3 = title_string3.getBytes("utf-8");
            String utf8_string3 = new String(bytes3, "utf-8");
            doc3.put("name", utf8_string3);
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }

        doc3.put("phone", "137****3333");

        int[] int_arr3 = {33,33};
        doc3.put("int_arr", int_arr3);

        String[] literal_arr3 = {"Update doc2 to doc3 in push mode","Update doc2 to doc3 in push mode"};
        doc3.put("literal_arr", literal_arr3);

        float[] float_arr3 = {(float)3.3,(float)3.3};
        doc3.put("float_arr", float_arr3);

        doc3.put("cate_id", 1);

        JSONObject json3 = new JSONObject();
        json3.put(DocumentConstants.DOC_KEY_CMD, Command.ADD.toString());
        json3.put(DocumentConstants.DOC_KEY_FIELDS, doc3);

        // doc4: DELETE — removes doc1 by primary key only                                   // (10)
        Map<String, Object> doc4 = Maps.newLinkedHashMap();
        doc4.put("id", value1);   // only the primary key is needed for deletion

        JSONObject json4 = new JSONObject();
        json4.put(DocumentConstants.DOC_KEY_CMD, Command.DELETE.toString());
        json4.put(DocumentConstants.DOC_KEY_FIELDS, doc4);

        // ---- Push documents ----

        JSONArray docsJsonArr = new JSONArray();
        docsJsonArr.put(json1);  // add doc1
        docsJsonArr.put(json2);  // add doc2
        docsJsonArr.put(json3);  // replace doc2 with doc3
        docsJsonArr.put(json4);  // delete doc1
        String docsJson = docsJsonArr.toString();

        // Initialize the client                                                             // (11)
        OpenSearch openSearch = new OpenSearch(accesskey, secret, host);
        OpenSearchClient serviceClient = new OpenSearchClient(openSearch);
        DocumentClient documentClient = new DocumentClient(serviceClient);

        try {
            OpenSearchResult osr = documentClient.push(docsJson, appName, tableName);       // (12)

            // A "true" result means the push request was accepted without errors.
            // Check the OpenSearch console error logs for any post-push processing errors
            // (such as field type conversion failures).
            if (osr.getResult().equalsIgnoreCase("true")) {
                System.out.println("Push accepted. Request ID: " + osr.getTraceInfo().getRequestId());
            } else {
                System.out.println("Push failed: " + osr.getTraceInfo());
            }

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }

        // ---- Query to verify ----

        // Wait 1 second for indexing to complete before querying                            // (13)
        try {
            Thread.sleep(1000);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }

        SearcherClient searcherClient = new SearcherClient(serviceClient);

        // Configure paging and return format                                                // (14)
        Config config = new Config(Lists.newArrayList(appName));
        config.setStart(0);
        config.setHits(30);
        config.setSearchFormat(SearchFormat.JSON);  // supported formats: XML, JSON (FULLJSON not supported)

        config.setFetchFields(Lists.newArrayList("id", "name", "phone", "int_arr", "literal_arr", "float_arr", "cate_id"));

        SearchParams searchParams = new SearchParams(config);

        // Query by primary key — match either value1 or value2                              // (15)
        // To query on multiple index fields, combine them in one setQuery call.
        // Each additional setQuery call overwrites the previous one.
        searchParams.setQuery("id:'" + value1 + "'|'" + value2 + "'");

        searchParams.setFilter("cate_id<=3");

        // Sort by id descending; break ties by RANK ascending                              // (16)
        Sort sorter = new Sort();
        sorter.addToSortFields(new SortField("id", Order.DECREASE));
        sorter.addToSortFields(new SortField("RANK", Order.INCREASE));
        searchParams.setSort(sorter);

        try {
            SearchResult searchResult = searcherClient.execute(searchParams);
            String result = searchResult.getResult();
            JSONObject obj = new JSONObject(result);
            System.out.println(obj.toString());

        } catch (OpenSearchException e) {
            e.printStackTrace();
        } catch (OpenSearchClientException e) {
            e.printStackTrace();
        }
    }
}

Annotations des commentaires :

#	Description
(1)	Définissez `appName` sur le nom de votre application OpenSearch.
(2)	Définissez `tableName` sur le nom de la table de l'application vers laquelle vous souhaitez envoyer des données.
(3)	Définissez `host` sur l'endpoint de l'API OpenSearch pour votre région.
(4)	Les identifiants sont lus à partir des variables d'environnement définies dans la section Configurer les identifiants.
(5)	Des entiers aléatoires servent de valeurs de clé primaire pour cet exemple. En production, utilisez vos IDs de document réels.
(6)	Chaque document est construit sous la forme d'un objet `Map<String, Object>`, puis encapsulé dans un objet `JSONObject` avec `DOC_KEY_CMD` et `DOC_KEY_FIELDS`.
(7)	`Command.ADD` ajoute un nouveau document si la clé primaire n'existe pas, ou remplace entièrement le document existant s'il existe.
(8)	Un deuxième document (`doc2`) est ajouté avec sa propre clé primaire unique (`value2`).
(9)	`doc3` utilise la même clé primaire que `doc2` (`value2`), donc la commande `ADD` remplace entièrement `doc2` par les valeurs des champs de `doc3`.
(10)	`Command.DELETE` supprime un document par clé primaire. Seul le champ de clé primaire est requis dans la charge utile.
(11)	Créez un objet `OpenSearch` avec vos identifiants et votre endpoint, puis utilisez-le pour initialiser `OpenSearchClient` et `DocumentClient`.
(12)	`documentClient.push()` soumet l'ensemble du lot en une seule requête. Un résultat `"true"` signifie que la requête a été acceptée ; vérifiez les journaux d'erreurs de la console pour les erreurs de traitement qui surviennent après l'envoi.
(13)	L'indexation est asynchrone. Une pause d'une seconde donne au moteur le temps d'indexer les documents avant l'exécution de la requête de vérification. En production, implémentez plutôt une stratégie de nouvelle tentative ou d'interrogation.
(14)	`Config` définit les paramètres de pagination (`start`, `hits`) et le format de réponse. `fetchFields` contrôle les champs renvoyés.
(15)	La requête utilise le champ d'index `id` pour faire correspondre l'une ou l'autre clé primaire. Il est nécessaire de combiner plusieurs champs dans un seul appel `setQuery` — chaque appel écrase le précédent.
(16)	Les résultats sont triés par `id` décroissant. Lorsque plusieurs documents partagent la même valeur `id`, ils sont triés par score de pertinence (`RANK`) croissant.