Elasticsearch:Java API Client (8.x)

背景情報

バージョン 7.17 より前の Elasticsearch は Java REST Client を使用します。Elasticsearch 7.17 から、Java REST Client は非推奨となり、Java API Client が推奨されています。

Java API Client の概要

Java API Client は、Elasticsearch サーバーとの通信を確立するために使用される Java クライアントライブラリです。Java API Client は、開発者が Elasticsearch クライアントと Elasticsearch サーバー間の通信を確立し、コードを簡単に開発および保守するのに役立ちます。

Java API Client は、次のコンポーネントで構成されています:

1. ElasticsearchClient クラス: ElasticsearchClient クラスは、Java API Client のコアクラスです。ElasticsearchClient クラスは、Elasticsearch サーバーとの通信を確立するために使用できるメソッドを提供します。ElasticsearchClient クラスは、Transport プロトコルをカプセル化し、同期および非同期の呼び出し、ストリーミング、および関数呼び出しを行うために使用されるメソッドを提供します。

2. JSON ObjectMapper: これは、シリアル化および逆シリアル化に使用されるライブラリです。JSON ObjectMapper は Jackson ライブラリとシームレスに統合されており、Java オブジェクトを JSON オブジェクトにシリアル化できます。

3. 共通機能: Java API Client は、接続プール、リトライ、JSON オブジェクト関連のシリアル化などの共通機能を提供します。Java API Client は、コードの可読性と保守性を向上させ、開発者のコード開発操作を容易にします。

準備

• Java 開発キット (JDK) をインストールします。JDK のバージョンは 1.8 以降である必要があります。詳細については、「JDK のインストール」をご参照ください。

• バージョンが Java API Client のバージョン以降である Alibaba Cloud Elasticsearch クラスターを作成します。この例では、Alibaba Cloud Elasticsearch V8.X クラスターが作成されます。詳細については、「Alibaba Cloud Elasticsearch クラスターの作成」をご参照ください。

  説明

  Java API Client の機能を使用できるようにするには、Elasticsearch クラスターのバージョンと同じバージョンの Java API Client を使用することをお勧めします。

• Elasticsearch クラスターの自動インデックス作成機能を有効にします。詳細については、「YML ファイルの設定」をご参照ください。自動インデックス作成機能が有効になっていない場合、次の図に示すエラーが報告されます。

• ネットワーク間の正常な通信を確保するために、Elasticsearch クラスターの IP アドレスホワイトリストを設定します。

  • Java コードを実行するサーバーがインターネット環境にある場合は、そのパブリックエンドポイントを使用してクラスターにアクセスできます。クラスターにアクセスする前に、クラスターのパブリックネットワークアクセス機能を有効にし、サーバーのパブリック IP アドレスをクラスターのパブリック IP アドレスホワイトリストに追加する必要があります。詳細については、「Elasticsearch クラスターのパブリックまたはプライベート IP アドレスホワイトリストの設定」をご参照ください。

    重要

    • クライアントがホームネットワークまたはオフィスの LAN にある場合は、クライアントのプライベート IP アドレスではなく、インターネット出口の IP アドレスをホワイトリストに追加する必要があります。

    • また、0.0.0.0/0 をホワイトリストに追加して、すべての IPv4 アドレスからのリクエストを許可することもできます。この設定を行うと、すべてのパブリック IP アドレスを使用してクラスターにアクセスできます。これにはセキュリティリスクが伴います。この設定を行う前に、リスクを評価することをお勧めします。

    • IP アドレスホワイトリストが設定されていないか、IP アドレスホワイトリストが正しく設定されていない場合、システムは「Timeout connecting」というエラーメッセージを報告して、接続タイムアウトエラーを示します。

    • クライアントからクラスター内の Kibana ノードにアクセスする場合は、Kibana の IP アドレスホワイトリストを設定する必要があります。詳細については、「Kibana のパブリックまたはプライベート IP アドレスホワイトリストの設定」をご参照ください。

  • Java コードを実行するサーバーが Elasticsearch クラスターと同じ VPC にある場合は、その内部エンドポイントを使用してクラスターにアクセスできます。Elasticsearch クラスターにアクセスする前に、サーバーのプライベート IP アドレスがクラスターのプライベート IP アドレスホワイトリストに追加されていることを確認してください。デフォルトでは、0.0.0.0/0 がホワイトリストに追加されています。

Elasticsearch クライアントと Elasticsearch サーバー間の通信を確立するための設定

Elasticsearch は、次のタイプのクライアントを初期化します:

• 低レベルクライアント

      // 低レベルクライアントを作成します
      RestClient restClient = RestClient.builder(
          new HttpHost("localhost", 9200,"http")).build();

• JacksonJsonpMapper クラスを使用してデータを解析するトランスポートクライアント

      // Jackson マッパーを使用してトランスポートを作成します
      ElasticsearchTransport transport = new RestClientTransport(
          restClient, new JacksonJsonpMapper());

• ブロッキング Java クライアント

      // そして API クライアントを作成します
      ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
      System.out.println("elasticsearchClient = " + elasticsearchClient);

POM 依存関係

次の Project Object Model (POM) 依存関係を使用する場合、8.x を使用する Java API Client のバージョンに置き換える必要があります。

<dependency>
    <groupId>co.elastic.clients</groupId>
    <artifactId>elasticsearch-java</artifactId>
    <version>8.x</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.12.3</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.20.0</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.20.0</version>
</dependency>

例

次のサンプルコードでは、{} で囲まれたパラメーターを実際の値に置き換えてください。

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.indices.*;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
import org.elasticsearch.client.*;


import java.io.IOException;

public class RestClientTest {
    public static void main(String[] args) {

        // Alibaba Cloud Elasticsearch クラスターには基本認証が必要です。
        final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();

        // ユーザー名とパスワードは、Alibaba Cloud Elasticsearch インスタンスの作成時に設定したものです。これらは Kibana コンソールへのログインにも使用されます。
        credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{Username}", "{Password}"));
        // ビルダーを使用して REST クライアントを作成し、HTTP クライアントの HttpClientConfigCallback を設定します。
        // 作成した Elasticsearch インスタンスの ID をクリックします。基本情報ページで、パブリックエンドポイントを取得します。これが ES クラスターのエンドポイントです。
        RestClient restClient = RestClient.builder(new HttpHost("{ES cluster endpoint}", 9200, "http"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                    }
                }).build();

        // Jackson マッパーを使用してトランスポートを作成します。
        ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());

        // API クライアントを作成します。
        ElasticsearchClient elasticsearchClient = new ElasticsearchClient(transport);
        //System.out.println("elasticsearchClient = " + elasticsearchClient);


        // インデックスを作成および削除し、すべてのインデックスに関する情報を表示します。
        // "foo" という名前のエイリアスを作成し、書き込みインデックスとして設定します。これは、インデックス作成、ドキュメントの更新、削除などのすべての書き込み操作が、このエイリアスに対応するインデックスに自動的にルーティングされることを意味します。
        try {
            // インデックスを作成します。
            CreateIndexResponse indexRequest = elasticsearchClient.indices().create(createIndexBuilder -> createIndexBuilder
                    .index("{index_name}")
                    .aliases("{foo}", aliasBuilder -> aliasBuilder
                            .isWriteIndex(true)
                    )
                );
            // "indexRequest" リクエストの操作が Elasticsearch クラスターによって承認されたかどうかを確認します。
            boolean acknowledged = indexRequest.acknowledged();
            System.out.println("Index document successfully! " + acknowledged);

            // インデックスを削除します。
            DeleteIndexResponse deleteResponse = elasticsearchClient.indices().delete(createIndexBuilder -> createIndexBuilder
                    .index("{index_name}")
            );
            System.out.println("Delete document successfully! \n" + deleteResponse.toString());

            // すべてのインデックスに関する情報 (health、status、index、uuid、pri、rep) を表示します。
            IndicesResponse indicesResponse = elasticsearchClient.cat().indices();
            indicesResponse.valueBody().forEach(info -> System.out.println(info.health() + "\t"+  info.status() + "\t" + info.index() + "\t" + info.uuid() +"\t" + info.pri() + "\t" + info.rep()));


            transport.close();
            restClient.close();
        } catch (IOException ioException) {
            // 例外を処理します。
        }
    }
}

高同時実行シナリオでは、クライアント接続数に関連する設定を追加する必要があります。次のコードに例を示します:

httpClientBuilder.setMaxConnTotal(500); 
httpClientBuilder.setMaxConnPerRoute(300);

サンプルコード:

String host = "localhost";
int port = 9200;
String username = "elastic";
String password = "passwd";
final int max_conn_total = 500;
final int max_conn_per_route = 300;

    RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200, "http"))
                .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
                    @Override
                    public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
                        httpClientBuilder.setMaxConnTotal(max_conn_total);
                        httpClientBuilder.setMaxConnPerRoute(max_conn_per_route);
                        return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
                    }
                }).build();

Java API Client の機能の詳細については、「公式 Java API Client ドキュメント」をご参照ください。