【最佳实践】Elasticsearch Java Rest Client快速上手（附完整示例代码包）

本文介绍Elasticsearch的Java Client的原理、版本兼容性以及使用示例，帮助您快速使用Java客户端与Elasticsearch集群进行交互，完成检索、分析等相关业务。

Transport Client迁移至REST Client

Transport Client随着Elasticsearch的第一个版本诞生，是一个特别的客户端。特别之处在于，它使用TCP协议与Elasticsearch通信，这也造成了当客户端与不同版本的Elasticsearch通信时，会存在兼容性问题。详情请参见Motivations around a new Java client。

Elasticsearch官网于2016年发布Low Level REST客户端，该客户端基于Apache HTTP客户端，允许通过HTTP协议与任何版本的Elasticsearch集群通信。在Low Level REST客户端的基础上，Elasticsearch发布了High Level REST Client。

Elasticsearch 7.0中已经弃用Transport Client，在8.0中完全移除它。因此在实际开发中建议您使用Java REST Client。Rest Client通过HTTP请求，帮助您处理请求和返回的序列化问题，为您的业务开发带来便捷。

Java REST客户端

Java REST客户端有两种类型：

• Java Low Level REST Client：Elasticsearch Client低级别客户端。它允许通过HTTP请求与Elasticsearch集群进行通信。API本身不负责数据的编码解码，由用户去编码解码。它与所有的Elasticsearch版本兼容。

• Java High Level REST Client（本章节以此为例）：Elasticsearch Client官方高级客户端。基于低级客户端，主要目标是为了暴露各API特定的方法。Java High Level REST Client依赖于Elasticsearch核心项目，将Request对象作为参数，返回一个Response对象。所有API都可以同步或异步调用。

  • 同步调用方法立即返回一个Response对象。
  • 而异步调用方法（方法名以async结尾）依赖于监听，当有请求返回或是错误返回时，该监听会通知到对应的方法继续执行。

本文以阿里云Elasticsearch为例，为您讲解Java Client的用法。阿里云Elasticsearch兼容开源Elasticsearch的功能，以及Security、Machine Learning、Graph、APM等商业功能，致力于数据分析、数据搜索等场景服务。支持5.5.3、6.3.2、6.7.0、6.8.0和7.4.0等版本，并提供了商业插件X-Pack服务。在开源Elasticsearch的基础上提供企业级权限管控、安全监控告警、自动报表生成等功能。阿里云Elasticsearch为您提供1个月的免费试用活动，单击此处即可免费试用。

准备工作

• 安装Java，要求JDK版本为1.8及以上。

  安装方法请参见安装JDK。

• 创建阿里云Elasticsearch实例，版本要求大于等于Java High Level REST Client的版本。

  创建对应版本的实例，具体操作方法请参见创建阿里云Elasticsearch实例。

  High Level Client能够向上兼容，例如7.4.0版本的Java High Level REST Client能确保与大于等于7.4.0版本的Elasticsearch集群通信。为了保证最大程度地使用最新版客户端的特性，推荐High Level Client版本与集群版本一致。

• 开启阿里云Elasticsearch实例的自动创建索引功能。
  具体操作步骤请参见开启自动创建索引。

如果未开启会提示如下报错。

• 配置阿里云Elasticsearch实例的白名单，确保网络互通。

  • 如果运行Java代码的服务器在公网环境下，可通过阿里云Elasticsearch实例的公网地址进行连通。连通前，需要开启阿里云Elasticsearch实例的公网地址，并修改公网地址访问白名单，将服务器的公网IP地址加入白名单中。具体操作步骤请参见配置ES公网或私网访问白名单。

  • 如果您使用的是WIFI、宽带等网络，需要将公网出口的跳板机IP地址配置进去。建议您通过淘宝IP地址库查询。
  • 您也可以将白名单配置为0.0.0.0/0，允许所有IPv4地址访问阿里云Elasticsearch实例。此配置会导致实例完全暴露在公网中，增加安全风险，配置前请确认您是否可以接受这个风险。

  • 如果运行Java代码的服务器与阿里云Elasticsearch实例在同一专有网络VPC（Virtual Private
    Cloud）中，可通过阿里云Elasticsearch实例的内网地址进行连通。连通前，需要确保VPC私网访问白名单（默认为0.0.0.0/0）中已添加了服务器的内网IP地址。
• 创建Java Maven工程，并将pom依赖添加到Java工程的pom.xml文件中。

High Level REST Client（7.x）

#### pom依赖

<dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>7.4.0</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.7</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.7</version> </dependency>

示例

单击下载完整示例代码。

以下代码使用Index API创建索引，使用Delete API删除该索引，并演示了在JVM内存分配比较有限的客户端环境中，通过调整ResponseConsumer配置，限制异步响应所占用的缓存的大小。

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.action.delete.DeleteRequest; import org.elasticsearch.action.delete.DeleteResponse; import org.elasticsearch.action.index.IndexRequest; import org.elasticsearch.action.index.IndexResponse; import org.elasticsearch.client.*; import java.io.IOException; import java.util.HashMap; import java.util.Map; public class RestClientTest74 { private static final RequestOptions COMMON_OPTIONS; static { RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder(); // 默认缓存限制为100MB，此处修改为30MB。 builder.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024)); COMMON_OPTIONS = builder.build(); } public static void main(String[] args) { // 阿里云Elasticsearch集群需要basic auth验证。 final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); //访问用户名和密码为您创建阿里云Elasticsearch实例时设置的用户名和密码，也是Kibana控制台的登录用户名和密码。 credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{访问用户名}", "{访问密码}")); // 通过builder创建rest client，配置http client的HttpClientConfigCallback。 // 单击所创建的Elasticsearch实例ID，在基本信息页面获取公网地址，即为ES集群地址。 RestClientBuilder builder = RestClient.builder(new HttpHost("{ES集群地址}", 9200)) .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { @Override public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); } }); // RestHighLevelClient实例通过REST low-level client builder进行构造。 RestHighLevelClient highClient = new RestHighLevelClient(builder); try { // 创建request。 Map<String, Object> jsonMap = new HashMap<>(); // field_01、field_02为字段名，value_01、value_02为对应的值。 jsonMap.put("{field_01}", "{value_01}"); jsonMap.put("{field_02}", "{value_02}"); //index_name为索引名称；type_name为类型名称,7.0及以上版本必须为_doc；doc_id为文档的id。 IndexRequest indexRequest = new IndexRequest("{index_name}", "_doc", "{doc_id}").source(jsonMap); // 同步执行，并使用自定义RequestOptions（COMMON_OPTIONS）。 IndexResponse indexResponse = highClient.index(indexRequest, COMMON_OPTIONS); long version = indexResponse.getVersion(); System.out.println("Index document successfully! " + version); //index_name为索引名称；type_name为类型名称,7.0及以上版本必须为_doc；doc_id为文档的id。与以上创建索引的名称和id相同。 DeleteRequest request = new DeleteRequest("{index_name}", "_doc", "{doc_id}"); DeleteResponse deleteResponse = highClient.delete(request, COMMON_OPTIONS); System.out.println("Delete document successfully! \n" + deleteResponse.toString() + "\n" + deleteResponse.status()); highClient.close(); } catch (IOException ioException) { // 异常处理。 } } }

以上示例代码中带{}的参数需要替换为您具体业务的参数，详情请参见代码注释。
更多Java High Level REST Client的使用特性，请参见Java High Level REST Client官方文档。

High Level REST Client（6.7.x）

pom依赖

<dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.7.0</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.7</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.7</version> </dependency>

RequestOptions新特性

相较于6.3.2的REST Client，6.7.0增加了RequestOptions选项。您可以通过它对请求进行更多自定义的配置，且不影响正常的Elasticsearch请求。
以下示例将演示在JVM内存分配比较有限的客户端环境中，通过调整ResponseConsumer配置，限制异步响应所占用的缓存的大小。完整示例请参见示例。

private static final RequestOptions COMMON_OPTIONS; static { RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder(); // 默认缓存限制为100MB，此处修改为30MB。 builder.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024)); COMMON_OPTIONS = builder.build(); }

// 同步执行，并使用自定义的RequestOptions（COMMON_OPTIONS）。 IndexResponse indexResponse = highClient.index(indexRequest, COMMON_OPTIONS);

更多RequestOptions的用法请参见官方文档。

示例

单击下载完整示例代码。
以下代码使用Index API创建索引，使用Delete API删除该索引，并演示了在JVM内存分配比较有限的客户端环境中，通过调整ResponseConsumer配置，限制异步响应所占用的缓存的大小。

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.action.delete.DeleteRequest; import org.elasticsearch.action.delete.DeleteResponse; import org.elasticsearch.action.index.IndexRequest; import org.elasticsearch.action.index.IndexResponse; import org.elasticsearch.client.*; import java.io.IOException; import java.util.HashMap; import java.util.Map; public class RestClientTest67 { private static final RequestOptions COMMON_OPTIONS; static { RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder(); // 默认缓存限制为100MB，此处修改为30MB。 builder.setHttpAsyncResponseConsumerFactory( new HttpAsyncResponseConsumerFactory .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024)); COMMON_OPTIONS = builder.build(); } public static void main(String[] args) { // 阿里云Elasticsearch集群需要basic auth验证。 final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); //访问用户名和密码为您创建阿里云Elasticsearch实例时设置的用户名和密码，也是Kibana控制台的登录用户名和密码。 credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{访问用户名}", "{访问密码}")); // 通过builder创建rest client，配置http client的HttpClientConfigCallback。 // 单击所创建的Elasticsearch实例ID，在基本信息页面获取公网地址，即为ES集群地址。 RestClientBuilder builder = RestClient.builder(new HttpHost("{ES集群地址}", 9200)) .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { @Override public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); } }); // RestHighLevelClient实例通过REST low-level client builder进行构造。 RestHighLevelClient highClient = new RestHighLevelClient(builder); try { // 创建request。 Map<String, Object> jsonMap = new HashMap<>(); // field_01、field_02为字段名，value_01、value_02为对应的值。 jsonMap.put("{field_01}", "{value_01}"); jsonMap.put("{field_02}", "{value_02}"); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。 IndexRequest indexRequest = new IndexRequest("{index_name}", "{type_name}", "{doc_id}").source(jsonMap); // 同步执行，并使用自定义RequestOptions（COMMON_OPTIONS）。 IndexResponse indexResponse = highClient.index(indexRequest, COMMON_OPTIONS); long version = indexResponse.getVersion(); System.out.println("Index document successfully! " + version); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。与以上创建索引的名称和id相同。 DeleteRequest request = new DeleteRequest("{index_name}", "{type_name}", "{doc_id}"); DeleteResponse deleteResponse = highClient.delete(request, COMMON_OPTIONS); System.out.println("Delete document successfully! \n" + deleteResponse.toString() + "\n" + deleteResponse.status()); highClient.close(); } catch (IOException ioException) { // 异常处理。 } } }

以上示例代码中带{}的参数需要替换为您具体业务的参数，详情请参见代码注释。
更多Java High Level REST Client的使用特性，请参见Java High Level REST Client官方文档。

High Level REST Client（6.3.x）

pom依赖

<dependency> <groupId>org.elasticsearch</groupId> <artifactId>elasticsearch</artifactId> <version>6.3.2</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.3.2</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.7</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.7</version> </dependency>

示例

单击下载完整示例代码。
以下示例使用Index API创建索引，然后使用Delete API删除该索引。

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.action.delete.DeleteRequest; import org.elasticsearch.action.delete.DeleteResponse; import org.elasticsearch.action.index.IndexRequest; import org.elasticsearch.action.index.IndexResponse; import org.elasticsearch.client.RestClient; import org.elasticsearch.client.RestClientBuilder; import org.elasticsearch.client.RestHighLevelClient; import java.io.IOException; import java.util.HashMap; import java.util.Map; public class RestClientTest63 { public static void main(String[] args) { // 阿里云Elasticsearch集群需要basic auth验证。 final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); //访问用户名和密码为您创建阿里云Elasticsearch实例时设置的用户名和密码，也是Kibana控制台的登录用户名和密码。 credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("{访问用户名}", "{访问密码}")); // 通过builder创建rest client，配置http client的HttpClientConfigCallback。 // 单击所创建的Elasticsearch实例ID，在基本信息页面获取公网地址，即为ES集群地址。 RestClientBuilder builder = RestClient.builder(new HttpHost("{ES集群地址}", 9200)) .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { @Override public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); } }); // RestHighLevelClient实例通过REST low-level client builder进行构造。 RestHighLevelClient highClient = new RestHighLevelClient(builder); try { // 创建request。 Map<String, Object> jsonMap = new HashMap<>(); // field_01、field_02为字段名，value_01、value_02为对应的值。 jsonMap.put("{field_01}", "{value_01}"); jsonMap.put("{field_02}", "{value_02}"); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。 IndexRequest indexRequest = new IndexRequest("{index_name}", "{type_name}", "{doc_id}").source(jsonMap); // 同步执行。 IndexResponse indexResponse = highClient.index(indexRequest); long version = indexResponse.getVersion(); System.out.println("Index document successfully! " + version); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。与以上创建索引的名称和id相同。 DeleteRequest request = new DeleteRequest("{index_name}", "{type_name}", "{doc_id}"); DeleteResponse deleteResponse = highClient.delete(request); System.out.println("Delete document successfully!"); highClient.close(); } catch (IOException ioException) { // 异常处理。 } } }

以上示例代码中带{}的参数需要替换为您具体业务的参数，详情请参见代码注释。
更多Java High Level REST Client的使用特性，请参见Java High Level REST Client官方文档。

Low Level REST Client (5.x)

pom依赖

<dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>rest</artifactId> <version>5.5.3</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.7</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.7</version> </dependency>

示例

单击下载完整示例代码。

通过Java REST Client访问阿里云Elasticsearch的9200端口进行测试，示例代码如下。

import org.apache.http.HttpEntity; 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.entity.ContentType; import org.apache.http.impl.client.BasicCredentialsProvider; import org.apache.http.impl.nio.client.HttpAsyncClientBuilder; import org.apache.http.nio.entity.NStringEntity; import org.apache.http.util.EntityUtils; import org.elasticsearch.client.Response; import org.elasticsearch.client.RestClient; import org.elasticsearch.client.RestClientBuilder; import java.io.IOException; import java.util.Collections; public class RestClientTest55 { public static void main(String[]args){ final CredentialsProvider credentialsProvider = new BasicCredentialsProvider(); credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("USER NAME", "PASSWORD")); // 单击所创建的Elasticsearch实例ID，在基本信息页面获取公网地址，即为HOST。 RestClient restClient = RestClient.builder(new HttpHost("HOST", 9200)) .setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() { @Override public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) { return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider); } }).build(); try { //field_01、field_02为字段名，value_01、value_02为对应的值。 HttpEntity entity = new NStringEntity("{\n\"field_01\" : \"value_01\"\n,\n\"field_02\" : \"value_02\"\n}", ContentType.APPLICATION_JSON); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。 Response indexResponse = restClient.performRequest( "PUT", "/index_name/type_name/doc_id", Collections.<String, String>emptyMap(), entity); //index_name为索引名称；type_name为类型名称；doc_id为文档的id。与以上创建索引的名称和id相同。 Response response = restClient.performRequest("GET", "/index_name/type_name/doc_id", Collections.singletonMap("pretty", "true")); System.out.println(EntityUtils.toString(response.getEntity())); } catch (IOException e) { e.printStackTrace(); } } }

• USER NAME：替换为访问阿里云Elasticsearch实例的用户名。
• PASSWORD：替换为访问阿里云Elasticsearch实例的密码。
• HOST：替换为阿里云Elasticsearch实例的内网或外网地址。可在实例的基本信息页面获取，获取方法请参见查看实例的基本信息。

相关活动

更多折扣活动，请访问阿里云 Elasticsearch 官网。

阿里云 Elasticsearch 商业通用版，1核2G ,SSD 20G首月免费
阿里云 Logstash 2核4G首月免费