Elasticsearch Clients

本章介绍受支持的 Elasticsearch 客户端实现的配置和用法。

This chapter illustrates configuration and usage of supported Elasticsearch client implementations.

Spring 数据 Elasticsearch 在 Elasticsearch 客户端（由 Elasticsearch 客户端库提供）上运行，该客户端连接到单个 Elasticsearch 节点或集群。尽管 Elasticsearch 客户端可直接用于与集群合作，但使用 Spring 数据 Elasticsearch 的应用程序通常使用 Elasticsearch Operations 和 Elasticsearch Repositories 的更高级抽象。

Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is connected to a single Elasticsearch node or a cluster. Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of Elasticsearch Operations and Elasticsearch Repositories.

Imperative Rest Client

要使用命令式（非反应式）客户端，必须配置一个配置 Bean，如下所示：

To use the imperative (non-reactive) client, a configuration bean must be configured like this:

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	for a detailed description of the builder methods see Client Configuration

ElasticsearchConfiguration 类允许通过覆盖 jsonpMapper() 或 transportOptions() 方法进行进一步配置。

The ElasticsearchConfiguration class allows further configuration by overriding for example the jsonpMapper() or transportOptions() methods.

然后，可以在其他 Spring 组件中注入以下 Bean：

The following beans can then be injected in other Spring components:

import org.springframework.beans.factory.annotation.Autowired;@Autowired
ElasticsearchOperations operations;      1

@Autowired
ElasticsearchClient elasticsearchClient; 2

@Autowired
RestClient restClient;                   3

@Autowired
JsonpMapper jsonpMapper;                 4

1	an implementation of `ElasticsearchOperations`
2	the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used.
3	the low level `RestClient` from the Elasticsearch libraries
4	the `JsonpMapper` user by the Elasticsearch `Transport`

基本上，只需要使用 ElasticsearchOperations 与 Elasticsearch 集群交互。使用存储库时，此实例也会在后台使用。

Basically one should just use the ElasticsearchOperations to interact with the Elasticsearch cluster. When using repositories, this instance is used under the hood as well.

Reactive Rest Client

在使用反应堆堆栈时，配置必须来自不同的类：

When working with the reactive stack, the configuration must be derived from a different class:

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	for a detailed description of the builder methods see Client Configuration

ReactiveElasticsearchConfiguration 类允许通过覆盖 jsonpMapper() 或 transportOptions() 方法进行进一步配置。

The ReactiveElasticsearchConfiguration class allows further configuration by overriding for example the jsonpMapper() or transportOptions() methods.

然后，可以在其他 Spring 组件中注入以下 Bean：

The following beans can then be injected in other Spring components:

@Autowired
ReactiveElasticsearchOperations operations;      1

@Autowired
ReactiveElasticsearchClient elasticsearchClient; 2

@Autowired
RestClient restClient;                           3

@Autowired
JsonpMapper jsonpMapper;                         4

可以注入以下内容：

the following can be injected:

1	an implementation of `ReactiveElasticsearchOperations`
2	the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used. This is a reactive implementation based on the Elasticsearch client implementation.
3	the low level `RestClient` from the Elasticsearch libraries
4	the `JsonpMapper` user by the Elasticsearch `Transport`

基本上，只需要使用 ReactiveElasticsearchOperations 与 Elasticsearch 集群交互。使用存储库时，此实例也会在后台使用。

Basically one should just use the ReactiveElasticsearchOperations to interact with the Elasticsearch cluster. When using repositories, this instance is used under the hood as well.

Client Configuration

可以通过 ClientConfiguration 更改客户端行为，该配置允许设置 SSL、连接和套接字超时、头和其他参数的选项。

Client behaviour can be changed via the ClientConfiguration that allows to set options for SSL, connect and socket timeouts, headers and other parameters.

Example 1. Client Configuration

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	Define default headers, if they need to be customized
2	Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
3	Optionally enable SSL.There exist overloads of this function that can take a `SSLContext` or as an alternative the fingerprint of the certificate as it is output by Elasticsearch 8 on startup.
4	Optionally set a proxy.
5	Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
6	Set the connection timeout.
7	Set the socket timeout.
8	Optionally set headers.
9	Add basic authentication.
10	A `Supplier<HttpHeaders>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.
11	a function to configure the created client (see Client configuration callbacks), can be added multiple times.

添加 Header 供应商（如上例所示）允许注入可能随时间而改变的标头，如身份验证 JWT 令牌。如果在反应性设置中使用，则供应商函数 must not 会被阻塞！

Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens. If this is used in the reactive setup, the supplier function must not block!

Client configuration callbacks

ClientConfiguration 类提供了最常见的参数来配置客户端。如果这还不够，用户可以使用 withClientConfigurer(ClientConfigurationCallback<?>) 方法添加回调函数。

The ClientConfiguration class offers the most common parameters to configure the client. In the case this is not enough, the user can add callback functions by using the withClientConfigurer(ClientConfigurationCallback<?>) method.

提供了以下回调：

The following callbacks are provided:

Configuration of the low level Elasticsearch `RestClient`:

该回调提供了一个 org.elasticsearch.client.RestClientBuilder，可用于配置 Elasticsearch RestClient：

This callback provides a org.elasticsearch.client.RestClientBuilder that can be used to configure the Elasticsearch RestClient:

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

Configuration of the HttpAsyncClient used by the low level Elasticsearch `RestClient`:

该回调提供了一个 org.apache.http.impl.nio.client.HttpAsyncClientBuilder 以配置 RestClient 使用的 HttpClient。

This callback provides a org.apache.http.impl.nio.client.HttpAsyncClientBuilder to configure the HttpCLient that is used by the RestClient.

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

Client Logging

要查看实际发送到服务器的内容以及从服务器接收的内容，需要按如下代码片段所述开启传输级别的 Request / Response 日志记录。这可以通过将 tracer 包的级别设置为“跟踪”在 Elasticsearch 客户端中启用（见 [role="bare"][role="bare"]https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html）。

To see what is actually sent to and received from the server Request / Response logging on the transport level needs to be turned on as outlined in the snippet below. This can be enabled in the Elasticsearch client by setting the level of the tracer package to "trace" (see [role="bare"]https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html)

Enable transport layer logging

<logger name="tracer" level="trace"/>