Elasticsearch 客户端

本章阐述了受支持的 Elasticsearch 客户端实现的配置和使用方法。spring-doc.cadn.net.cn

Spring Data Elasticsearch 基于一个 Elasticsearch 客户端（由 Elasticsearch 客户端库提供），该客户端可连接到单个 Elasticsearch 节点或集群。 尽管可以直接使用 Elasticsearch 客户端与集群交互，但使用 Spring Data Elasticsearch 的应用程序通常会采用更高级的抽象：Elasticsearch 操作和Elasticsearch 仓库。spring-doc.cadn.net.cn

命令式 Rest5Client

要使用命令式（非响应式）Rest5Client——即从版本 9 开始由 Elasticsearch Java 客户端库提供的默认客户端——必须按如下方式配置一个配置 Bean：spring-doc.cadn.net.cn

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 类允许通过重写例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。spring-doc.cadn.net.cn

以下 Bean 随后可注入到其他 Spring 组件中：spring-doc.cadn.net.cn

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

@Autowired
ElasticsearchOperations operations;      (1)

@Autowired
ElasticsearchClient elasticsearchClient; (2)

@Autowired
Rest5Client rest5Client;                 (3)

@Autowired
JsonpMapper jsonpMapper;                 (4)
1 ElasticsearchOperations 的一种实现
2 使用的 co.elastic.clients.elasticsearch.ElasticsearchClient。
3 来自 Elasticsearch 库的底层 Rest5Client
4 Elasticsearch Transport 的第 JsonpMapper 个用户

基本上，应该只使用 ElasticsearchOperations 来与 Elasticsearch 集群进行交互。 当使用仓库时，该实例也会在底层被使用。spring-doc.cadn.net.cn

已弃用的命令式 RestClient

要使用命令式（非响应式）的 RestClient（自版本 6 起已弃用），需要添加以下依赖项，并适配正确的版本。在 Spring Boot 应用程序中需要进行排除：spring-doc.cadn.net.cn

        <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：spring-doc.cadn.net.cn

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 类允许通过重写例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。spring-doc.cadn.net.cn

以下 Bean 随后可注入到其他 Spring 组件中：spring-doc.cadn.net.cn

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

@Autowired
ElasticsearchOperations operations;      (1)

@Autowired
ElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                   (3)

@Autowired
JsonpMapper jsonpMapper;                 (4)
1 ElasticsearchOperations 的一种实现
2 使用的 co.elastic.clients.elasticsearch.ElasticsearchClient。
3 来自 Elasticsearch 库的底层 RestClient
4 Elasticsearch Transport 的第 JsonpMapper 个用户

基本上，应该只使用 ElasticsearchOperations 来与 Elasticsearch 集群进行交互。 当使用仓库时，该实例也会在底层被使用。spring-doc.cadn.net.cn

响应式 Rest5Client

在使用响应式技术栈时，配置必须源自一个不同的类：spring-doc.cadn.net.cn

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 类允许通过重写例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。spring-doc.cadn.net.cn

以下 Bean 随后可注入到其他 Spring 组件中：spring-doc.cadn.net.cn

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

@Autowired
ReactiveElasticsearchOperations operations;      (1)

@Autowired
ReactiveElasticsearchClient elasticsearchClient; (2)

@Autowired
Rest5Client rest5Client;                           (3)

@Autowired
JsonpMapper jsonpMapper;                         (4)

以下内容可以被注入：spring-doc.cadn.net.cn

1 ReactiveElasticsearchOperations 的一种实现
2 使用的 org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient。 这是基于 Elasticsearch 客户端实现的响应式实现。
3 来自 Elasticsearch 库的底层 RestClient
4 Elasticsearch Transport 的第 JsonpMapper 个用户

基本上，应该只使用 ReactiveElasticsearchOperations 来与 Elasticsearch 集群进行交互。 当使用仓库时，该实例也会在底层被使用。spring-doc.cadn.net.cn

已弃用的响应式 Rest 客户端

请参阅上方章节，了解使用已弃用的 RestClient 所需的命令式代码及需要包含的依赖项。spring-doc.cadn.net.cn

在使用响应式技术栈时，配置必须源自一个不同的类：spring-doc.cadn.net.cn

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 类允许通过重写例如 jsonpMapper() 或 transportOptions() 方法进行进一步配置。spring-doc.cadn.net.cn

以下 Bean 随后可注入到其他 Spring 组件中：spring-doc.cadn.net.cn

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

@Autowired
ReactiveElasticsearchOperations operations;      (1)

@Autowired
ReactiveElasticsearchClient elasticsearchClient; (2)

@Autowired
RestClient restClient;                           (3)

@Autowired
JsonpMapper jsonpMapper;                         (4)

以下内容可以被注入：spring-doc.cadn.net.cn

1 ReactiveElasticsearchOperations 的一种实现
2 使用的 org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient。 这是基于 Elasticsearch 客户端实现的响应式实现。
3 来自 Elasticsearch 库的底层 RestClient
4 Elasticsearch Transport 的第 JsonpMapper 个用户

基本上，应该只使用 ReactiveElasticsearchOperations 来与 Elasticsearch 集群进行交互。 当使用仓库时，该实例也会在底层被使用。spring-doc.cadn.net.cn

客户端配置

客户端行为可以通过 ClientConfiguration 进行更改，该接口允许设置 SSL、连接和套接字超时、请求头以及其他参数。spring-doc.cadn.net.cn

示例 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 可以指定一个 Supplier<HttpHeaders> 函数，该函数在每次向 Elasticsearch 发送请求之前都会被调用——此处作为示例，将当前时间写入请求头中。
11 一个用于配置已创建客户端的函数（参见 客户端配置回调），可以多次添加。
如上例所示，添加一个 Header 供应器（Header supplier）可以注入可能随时间变化的头部信息，例如身份验证的 JWT Tokens。 如果在响应式设置中使用此功能，供应器函数 绝不能 阻塞！

客户端配置回调

ClientConfiguration 类提供了配置客户端最常用的参数。 如果这些参数不足，用户可以通过使用 withClientConfigurer(ClientConfigurationCallback<?>) 方法添加回调函数。spring-doc.cadn.net.cn

提供以下回调：spring-doc.cadn.net.cn

底层 Elasticsearch 的配置Rest5Client:

此回调提供一个org.elasticsearch.client.RestClientBuilder，可用于配置 Elasticsearch Rest5Client：spring-doc.cadn.net.cn

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

已弃用的底层 Elasticsearch 配置RestClient:

此回调提供一个org.elasticsearch.client.RestClientBuilder，可用于配置 Elasticsearch RestClient：spring-doc.cadn.net.cn

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

由底层 Elasticsearch 使用的 HttpAsyncClient 的配置Rest5Client:

此回调提供一个org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder，用于配置由Rest5Client使用的 HttpClient。spring-doc.cadn.net.cn

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

由已弃用的低级 Elasticsearch 使用的 HttpAsyncClient 的配置RestClient:

此回调提供一个org.apache.http.impl.nio.client.HttpAsyncClientBuilder，用于配置由RestClient使用的 HttpClient。spring-doc.cadn.net.cn

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

由底层 Elasticsearch 使用的 ConnectionConfig 的配置Rest5Client:

此回调提供一个org.apache.hc.client5.http.config.ConnectionConfig，用于配置由Rest5Client使用的连接。spring-doc.cadn.net.cn

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

由底层 Elasticsearch 使用的 ConnectionManager 的配置Rest5Client:

此回调提供一个org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder，用于配置由Rest5Client使用的连接管理器。spring-doc.cadn.net.cn

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

配置由底层 Elasticsearch 使用的 RequestConfigRest5Client:

此回调提供一个org.apache.hc.client5.http.config.RequestConfig来配置由Rest5Client使用的 RequestConfig。spring-doc.cadn.net.cn

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

客户端日志记录

要查看实际发送到服务器和从服务器接收的内容，需要按照下方代码片段所述，在传输级别启用 Request / Response 日志记录。 这可以通过将 co.elastic.clients.transport.rest5_client.low_level.Request 包的日志级别设置为 "trace" 在 Elasticsearch 客户端中启用（参见 www.elastic.co/docs/reference/elasticsearch/clients/java/transport/rest5-client/usage/logging）spring-doc.cadn.net.cn

启用传输层日志记录
<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