Elasticsearch Clients

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

Imperative Rest Client

要使用命令式（非反应式）客户端，必须配置一个配置 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	有关构建器方法的详细说明，请参阅 Client Configuration

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

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

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	使用的 `co.elastic.clients.elasticsearch.ElasticsearchClient`
3	来自 Elasticsearch 库的低级别 `RestClient`
4	Elasticsearch `Transport` 使用的 `JsonpMapper` 用户

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

Reactive Rest Client

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

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	有关构建器方法的详细说明，请参阅 Client Configuration

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

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

@Autowired
ReactiveElasticsearchOperations operations;      1

@Autowired
ReactiveElasticsearchClient elasticsearchClient; 2

@Autowired
RestClient restClient;                           3

@Autowired
JsonpMapper jsonpMapper;                         4

可以注入以下内容：

1	an implementation of `ReactiveElasticsearchOperations`
2	使用的 `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient`。这是基于 Elasticsearch 客户端实现的反应式实现。
3	来自 Elasticsearch 库的低级别 `RestClient`
4	Elasticsearch `Transport` 使用的 `JsonpMapper` 用户

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

Client Configuration

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

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	如果需要自定义，请定义默认标头
2	使用构建器来提供集群地址、设置默认 `HttpHeaders` 或启用 SSL。
3	可选启用 SSL。此功能存在可获取 `SSLContext` 或备用证书指纹（由 Elasticsearch 8 在启动时输出）的重载。
4	Optionally set a proxy.
5	可选设置路径前缀，主要用于某些反向代理后面的不同集群。
6	Set the connection timeout.
7	Set the socket timeout.
8	Optionally set headers.
9	Add basic authentication.
10	可以指定一个 `Supplier<HttpHeaders>` 函数，该函数在向 Elasticsearch 发送请求之前每次都会被调用 - 在这里，以当前时间为例，在标头中写入当前时间。
11	一个用于配置已创建的客户端（请参阅 Client configuration callbacks）的函数，可以多次添加。

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

Client configuration callbacks

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

提供了以下回调：

Configuration of the low level Elasticsearch `RestClient`:

该回调提供了一个 org.elasticsearch.client.RestClientBuilder，可用于配置 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。

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）。

Enable transport layer logging

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