Elasticsearch クライアント

この章では、サポートされている Elasticsearch クライアント実装の構成と使用箇所について説明します。

Spring Data Elasticsearch は、単一の Elasticsearch ノードまたはクラスターに接続された Elasticsearch クライアント (Elasticsearch クライアントライブラリによって提供) 上で動作します。Elasticsearch クライアントはクラスターで直接動作するために使用できますが、Spring Data Elasticsearch を使用するアプリケーションは通常、Elasticsearch オペレーションおよび Elasticsearch リポジトリのより高レベルの抽象化を使用します。

命令形 Rest5Client

命令型 (非リアクティブ) Rest5Client (バージョン 9 以降の Elasticsearch Java クライアントライブラリによって提供されるデフォルトのクライアント) を使用するには、構成 Bean を次のように構成する必要があります。

import org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration;

@Configuration
public class MyClientConfig extends ElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}
1 ビルダーメソッドの詳細については、クライアント構成を参照してください。

ElasticsearchConfiguration (Javadoc) クラスでは、たとえば jsonpMapper() または transportOptions() メソッドをオーバーライドすることで、さらに構成を行うことができます。

次に、次の Bean を他の Spring コンポーネントに注入できます。

import org.springframework.beans.factory.annotation.Autowired;

@Autowired
ElasticsearchOperations operations;      (1)

@Autowired
ElasticsearchClient elasticsearchClient; (2)

@Autowired
Rest5Client rest5Client;                 (3)

@Autowired
JsonpMapper jsonpMapper;                 (4)
1ElasticsearchOperations (Javadoc) の実装
2 使用されている co.elastic.clients.elasticsearch.ElasticsearchClient。
3Elasticsearch ライブラリの低レベル Rest5Client 
4JsonpMapper ユーザーによる Elasticsearch Transport

基本的に、ElasticsearchOperations (Javadoc) を使用して Elasticsearch クラスターと対話する必要があります。リポジトリを使用する場合、このインスタンスも内部で使用されます。

非推奨の命令形 RestClient

命令型（非リアクティブ）RestClient（バージョン 6 以降は非推奨）を使用するには、以下の依存関係を追加し、適切なバージョンを適用する必要があります。Spring Boot アプリケーションでは、この除外が必要です。

        <dependency>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-client</artifactId>
            <version>${elasticsearch-client.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>commons-logging</groupId>
                    <artifactId>commons-logging</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

構成 Bean は次のように構成する必要があります。

import org.springframework.data.elasticsearch.client.elc.ElasticsearchLegacyRestClientConfiguration;

@Configuration
public class MyClientConfig extends ElasticsearchLegacyRestClientConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}
1 ビルダーメソッドの詳細については、クライアント構成を参照してください。

ElasticsearchConfiguration (Javadoc) クラスでは、たとえば jsonpMapper() または transportOptions() メソッドをオーバーライドすることで、さらに構成を行うことができます。

次に、次の Bean を他の Spring コンポーネントに注入できます。

import org.springframework.beans.factory.annotation.Autowired;

@Autowired
ElasticsearchOperations operations;      (1)

@Autowired
ElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                   (3)

@Autowired
JsonpMapper jsonpMapper;                 (4)
1ElasticsearchOperations (Javadoc) の実装
2 使用されている co.elastic.clients.elasticsearch.ElasticsearchClient。
3Elasticsearch ライブラリの低レベル RestClient 
4JsonpMapper ユーザーによる Elasticsearch Transport

基本的に、ElasticsearchOperations (Javadoc) を使用して Elasticsearch クラスターと対話する必要があります。リポジトリを使用する場合、このインスタンスも内部で使用されます。

リアクティブ Rest5Client

リアクティブスタックを使用する場合、構成は別のクラスから派生する必要があります。

import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration;

@Configuration
public class MyClientConfig extends ReactiveElasticsearchConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}
1 ビルダーメソッドの詳細については、クライアント構成を参照してください。

ReactiveElasticsearchConfiguration (Javadoc) クラスでは、たとえば jsonpMapper() または transportOptions() メソッドをオーバーライドすることで、さらに構成を行うことができます。

次に、次の Bean を他の Spring コンポーネントに注入できます。

import org.springframework.beans.factory.annotation.Autowired;

@Autowired
ReactiveElasticsearchOperations operations;      (1)

@Autowired
ReactiveElasticsearchClient elasticsearchClient; (2)

@Autowired
Rest5Client rest5Client;                           (3)

@Autowired
JsonpMapper jsonpMapper;                         (4)

以下のものを注入できます。

1ReactiveElasticsearchOperations (Javadoc) の実装
2 使用される org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient。これは、Elasticsearch クライアント実装に基づくリアクティブ実装です。
3Elasticsearch ライブラリの低レベル RestClient 
4JsonpMapper ユーザーによる Elasticsearch Transport

基本的に、ReactiveElasticsearchOperations (Javadoc) を使用して Elasticsearch クラスターと対話する必要があります。リポジトリを使用する場合、このインスタンスも内部で使用されます。

非推奨のリアクティブ RestClient

必要な依存関係を含めるために非推奨の RestClient を使用するための命令型コードについては、上記のセクションを参照してください。

リアクティブスタックを使用する場合、構成は別のクラスから派生する必要があります。

import org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchLegacyRestClientConfiguration;

@Configuration
public class MyClientConfig extends ReactiveElasticsearchLegacyRestClientConfiguration {

	@Override
	public ClientConfiguration clientConfiguration() {
		return ClientConfiguration.builder()           (1)
			.connectedTo("localhost:9200")
			.build();
	}
}
1 ビルダーメソッドの詳細については、クライアント構成を参照してください。

ReactiveElasticsearchConfiguration (Javadoc) クラスでは、たとえば jsonpMapper() または transportOptions() メソッドをオーバーライドすることで、さらに構成を行うことができます。

次に、次の Bean を他の Spring コンポーネントに注入できます。

import org.springframework.beans.factory.annotation.Autowired;

@Autowired
ReactiveElasticsearchOperations operations;      (1)

@Autowired
ReactiveElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                           (3)

@Autowired
JsonpMapper jsonpMapper;                         (4)

以下のものを注入できます。

1ReactiveElasticsearchOperations (Javadoc) の実装
2 使用される org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient。これは、Elasticsearch クライアント実装に基づくリアクティブ実装です。
3Elasticsearch ライブラリの低レベル RestClient 
4JsonpMapper ユーザーによる Elasticsearch Transport

基本的に、ReactiveElasticsearchOperations (Javadoc) を使用して Elasticsearch クラスターと対話する必要があります。リポジトリを使用する場合、このインスタンスも内部で使用されます。

クライアント構成

クライアントの動作は、SSL、接続およびソケットのタイムアウト、ヘッダー、その他のパラメーターのオプションを設定できる ClientConfiguration (Javadoc) を介して変更できます。

例 1: クライアント構成 
import org.springframework.data.elasticsearch.client.ClientConfiguration;
import org.springframework.data.elasticsearch.support.HttpHeaders;

import static org.springframework.data.elasticsearch.client.elc.ElasticsearchClients.*;

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.add("some-header", "on every request")                      (1)

ClientConfiguration clientConfiguration = ClientConfiguration.builder()
  .connectedTo("localhost:9200", "localhost:9291")                      (2)
  .usingSsl()                                                           (3)
  .withProxy("localhost:8888")                                          (4)
  .withPathPrefix("ela")                                                (5)
  .withConnectTimeout(Duration.ofSeconds(5))                            (6)
  .withSocketTimeout(Duration.ofSeconds(3))                             (7)
  .withDefaultHeaders(defaultHeaders)                                   (8)
  .withBasicAuth(username, password)                                    (9)
  .withHeaders(() -> {                                                  (10)
    HttpHeaders headers = new HttpHeaders();
    headers.add("currentTime", LocalDateTime.now().format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
    return headers;
  })
  .withClientConfigurer(                                                (11)
    ElasticsearchHttpClientConfigurationCallback.from(clientBuilder -> {
  	  // ...
      return clientBuilder;
  	}))
  . // ... other options
  .build();
1 カスタマイズする必要がある場合は、デフォルトのヘッダーを定義します。
2 ビルダーを使用してクラスターアドレスを指定し、デフォルトの HttpHeaders を設定するか、SSL を有効にします。
3 オプションで SSL を有効にします。この関数には、SSLContext を受け取るか、代わりに起動時に Elasticsearch によって出力される証明書のフィンガープリントを受け取ることができるオーバーロードが存在します (バージョン 8 以降)。
4 必要に応じてプロキシを設定します。
5 オプションでパスプレフィックスを設定します。これは主に、リバースプロキシの背後にある異なるクラスターの場合に使用されます。
6 接続タイムアウトを設定します。
7 ソケットのタイムアウトを設定します。
8 必要に応じてヘッダーを設定します。
9 基本認証を追加します。
10 リクエストが Elasticsearch に送信される前に毎回呼び出される Supplier<HttpHeaders> 関数を指定できます。ここでは、例として、現在の時刻がヘッダーに書き込まれます。
11 作成されたクライアントを構成する関数 ( クライアント構成コールバックを参照) は複数回追加できます。
上の例に示すようにヘッダーサプライヤーを追加すると、認証 JWT トークンなど、時間の経過とともに変化する可能性のあるヘッダーを挿入できます。これをリアクティブ設定で使用する場合、サプライヤー機能をブロックしてはなりません。

クライアント構成コールバック

ClientConfiguration (Javadoc) クラスは、クライアントを構成するための最も一般的なパラメーターを提供します。これでは不十分な場合は、ユーザーは withClientConfigurer(ClientConfigurationCallback<?>) メソッドを使用してコールバック関数を追加できます。

次のコールバックが提供されます。

低レベル Elasticsearch Rest5Client の構成:

このコールバックは、Elasticsearch Rest5Client を構成するために使用できる org.elasticsearch.client.RestClientBuilder を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(Rest5Clients.ElasticsearchRest5ClientConfigurationCallback.from(restClientBuilder -> {
        // configure the Elasticsearch Rest5Client
        return restClientBuilder;
    }))
    .build();

非推奨の低レベル Elasticsearch RestClient の構成:

このコールバックは、Elasticsearch RestClient を構成するために使用できる org.elasticsearch.client.RestClientBuilder を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(RestClients.ElasticsearchRestClientConfigurationCallback.from(restClientBuilder -> {
        // configure the Elasticsearch RestClient
        return restClientBuilder;
    }))
    .build();

低レベル Elasticsearch Rest5Client で使用される HttpAsyncClient の構成:

このコールバックは、Rest5Client によって使用される HttpClient を構成するための org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(Rest5Clients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
        // configure the HttpAsyncClient
        return httpAsyncClientBuilder;
    }))
    .build();

非推奨の低レベル Elasticsearch RestClient で使用される HttpAsyncClient の構成:

このコールバックは、RestClient によって使用される HttpClient を構成するための org.apache.http.impl.nio.client.HttpAsyncClientBuilder を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(RestClients.ElasticsearchHttpClientConfigurationCallback.from(httpAsyncClientBuilder -> {
        // configure the HttpAsyncClient
        return httpAsyncClientBuilder;
    }))
    .build();

低レベル Elasticsearch Rest5Client で使用される ConnectionConfig の構成:

このコールバックは、Rest5Client によって使用される接続を構成するための org.apache.hc.client5.http.config.ConnectionConfig を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(Rest5Clients.ElasticsearchConnectionConfigurationCallback.from(connectionConfigBuilder -> {
        // configure the connection
        return connectionConfigBuilder;
    }))
    .build();

低レベル Elasticsearch Rest5Client で使用される ConnectionManager の構成:

このコールバックは、Rest5Client によって使用される接続マネージャーを構成するための org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(Rest5Clients.ElasticsearchConnectionManagerCallback.from(connectionManagerBuilder -> {
        // configure the connection manager
        return connectionManagerBuilder;
    }))
    .build();

低レベル Elasticsearch Rest5Client で使用される RequestConfig の構成:

このコールバックは、Rest5Client によって使用される RequestConfig を構成するための org.apache.hc.client5.http.config.RequestConfig を提供します。

ClientConfiguration.builder()
    .connectedTo("localhost:9200", "localhost:9291")
    .withClientConfigurer(Rest5Clients.ElasticsearchRequestConfigCallback.from(requestConfigBuilder -> {
        // configure the request config
        return requestConfigBuilder;
    }))
    .build();

クライアントロギング

実際にサーバーに送信され、サーバーから受信される内容を確認するには、以下のスニペットで概説されているように、トランスポートレベルで Request / Response ログをオンにする必要があります。これは、Elasticsearch クライアントで co.elastic.clients.transport.rest5_client.low_level.Request パッケージのレベルを「トレース」に設定することで有効にできます。(www.elastic.co/docs/reference/elasticsearch/clients/java/transport/rest5-client/usage/logging (英語) を参照してください)

トランスポート層のログを有効にする

  • XML

  • yml

  • ini

<logger name="co.elastic.clients.transport.rest5_client.low_level.Request" level="trace"/>
logging.level:
  co.elastic.clients.transport.rest5_client.low_level.Request: trace
logging.level.co.elastic.clients.transport.rest5_client.low_level.Request=trace