ElasticSearch-Java-low-level-rest-client官方文档翻译

人肉翻译，非谷歌机翻，部分地方添加了个人的理解，并做了分割，如有错误请在评论指出。转载请指明原链接，尊重个人劳动成果。

       High-Level-Rest-Client基于Low-Level-Rest-Client封装，Client配置方面基于Low-Level，而API使用上基于High-Level。

       翻译的版本为6.5.4版本的Elasticsearch，部分不重要的内容（如Maven/Gradle坐标、License等不在本文出现）。

       在实际的配置过程中，查看源码发现LowLevelClient完全基于HttpAsyncClient来实现的，内部具体组装Client的细节，如果有时间会写另外一篇博文分享出来。

 

低级别rest-client包含了如下特性：

• 最小的依赖
• 在集群所有结点间负载均衡
• 结点失败后，根据具体的响应码（response code）进行失效转移
• 连接失败惩罚机制（是否重连一个失败的结点取决于它失败的次数；尝试重新连接失败的次数越多，客户端下一次尝试重新连接该结点的等待时间也越长）
• 持久化连接
• 请求和响应的日志追踪
• （可选功能）集群结点自动发现

 

1、初始化客户端

1.1.基本设置

        RestClient实例只需要通过RestClientBuilder类进行构建就行，如下所示，可以提供多个连接实例的HttpHost（每一个HttpHost都是一个结点Node）：

 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200, "http"),
     new HttpHost("localhost", 9201, "http")).build();

        RestClient是线程安全的，并且和它依附的应用有相同的生命周期。需要注意的是，当不需要Client的时候，需要关闭它以便正确的释放其持有的资源（这些资源有底层的http client实例与它的线程）：

 restClient.close();

1.2.参数化设置

   RestClientBuilder同样允许参数化的设置如下参数来用于构建RestClient实例：

• 设置默认的请求头，该请求头会应用到每个request上去。不允许单独的在每次请求时进行请求头设置。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 Header[] defaultHeaders = new Header[]{new BasicHeader("header", "value")};
 builder.setDefaultHeaders(defaultHeaders);

• 设置同一个请求的多次尝试时的最大超时时间，这个设置默认的时间是30秒（同socket timeout的默认超时时间一样）。如果你修改了socket timeout，你也应该修改这个值来适应socket timeout。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 builder.setMaxRetryTimeoutMillis(10000); 

• 设置监听器，当一个结点故障时收到通知，以采取措施。嗅探失败节点功能会隐式的使用一个这样的监听器。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 builder.setFailureListener(new RestClient.FailureListener() {
     @Override
     public void onFailure(Node node) {

     }
 });

• 设置结点选择器，用于过滤某些es的结点（这些结点在初始化时设置到Client中）。当结点嗅探开启时，如果你不想将请求发送至dedicated master结点上，该功能很好用。Client默认会将请求发送到所有配置的节点上。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 builder.setNodeSelector(NodeSelector.SKIP_DEDICATED_MASTERS);

• 通过一个回调函数修改默认的请求配置（如超时时间、验证信息等其他apache httpclient包中RequestConfig.Builder允许的配置）。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 builder.setRequestConfigCallback(
     new RestClientBuilder.RequestConfigCallback() {
         @Override
         public RequestConfig.Builder customizeRequestConfig(
                 RequestConfig.Builder requestConfigBuilder) {
             return requestConfigBuilder.setSocketTimeout(10000);
         }
     });

• 通过一个回调函数修改默认的HttpClient配置（如ssl配置等其他apache httpclient包中HttpAsyncClientBuilder允许的配置）。

 RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "http"));
 builder.setHttpClientConfigCallback(new HttpClientConfigCallback() {
         @Override
         public HttpAsyncClientBuilder customizeHttpClient(
                 HttpAsyncClientBuilder httpClientBuilder) {
             return httpClientBuilder.setProxy(
                 new HttpHost("proxy", 9000, "http"));
         }
     });

2、执行请求

2.1.同步与异步API

        一旦Client创建，就可以通过performRequest或performRequestAsync来执行请求：

（1）performRequest是同步请求，它会阻塞调用线程，在请求成功或者请求失败抛出异常之后，返回Response；

 Request request = new Request(
     "GET",   //HTTP方法，支持GET、POST、HEAD等
     "/");    //es服务端点endpoint
 Response response = restClient.performRequest(request);

（2）performRequestAsync是异步请求，它接收一个ResponseListener参数，当请求成功或者请求失败抛出异常之后，该Listener会被调起并传入Response或Exception到相应方法；

 Request request = new Request(
     "GET",   //HTTP方法，支持GET、POST、HEAD等
     "/");    //es服务端点endpoint
 restClient.performRequestAsync(request, new ResponseListener() {
     @Override
     public void onSuccess(Response response) {
         //成功回调
     }

     @Override
     public void onFailure(Exception exception) {
         //失败回调
     }
 });

        另外，你可以向Request对象中添加请求参数，如下：

 request.addParameter("pretty", "true");

如果将HttpEntity设置为String，那么ContentType会被默认设置为application/json：

2.2.请求可选项

        RequestOptions这个类用于设置请求可选项，我们建议在同一个应用中，对于使用同样的请求可选项的Request共享一个RequestOption实例，你可以通过单例来实现：

 private static final RequestOptions COMMON_OPTIONS;
 static {
     RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder();
     builder.addHeader("Authorization", "Bearer " + TOKEN);  //设置请求头的校验信息
     builder.setHttpAsyncResponseConsumerFactory( //设置Response的缓冲池大小
         new HeapBufferedResponseConsumerFactory(30 * 1024 * 1024 * 1024));
     COMMON_OPTIONS = builder.build();
 }

• 这里有一个addHeader方法，需要注意的是，在这里不需要设置ContentType，因为在设置HttpEntity时就会自动关联ContentType；
• 你可以在这里设置NodeSelector。NodeSelector.NOT_MASTER_ONLY是一个比较好的选择；
• 你可以在这里定制用于缓冲异步响应的Response Consumer。默认的ResponseConsumer会在JVM堆上缓存100M的响应数据。如果响应数据比缓冲区过大，当次请求会失败。如果你的应用跑在一个JVM堆比较小的环境中，你需要降低缓冲区的最大值。

        配置好RequestOptions之后，我们在每一个共享该配置的Request中，简单设置一下该对象即可：

 request.setOptions(COMMON_OPTIONS);

如果有某些请求需要对OPTIONS做一定程度的变更，可以通过如下方式增量处理而不是重新写一遍设置代码：

 RequestOptions.Builder options = COMMON_OPTIONS.toBuilder();
 options.addHeader("cats", "knock things off of other things");
 request.setOptions(options); 

2.3.批量并行异步请求

下面是一个使用闭锁并行执行异步请求的例子。在实际的编程中，你一般会倾向于使用_bulk这个API来替代，当然了，下面的例子依然具有参考性：

 final CountDownLatch latch = new CountDownLatch(documents.length);
 for (int i = 0; i < documents.length; i++) {
     Request request = new Request("PUT", "/posts/doc/" + i);
     //let's assume that the documents are stored in an HttpEntity array
     request.setEntity(documents[i]);
     restClient.performRequestAsync(
             request,
             new ResponseListener() {
                 @Override
                 public void onSuccess(Response response) {

                     latch.countDown();
                 }

                 @Override
                 public void onFailure(Exception exception) {

                     latch.countDown();
                 }
             }
     );
 }
 latch.await();

3、读取响应

3.1.获取响应对象

        响应对象，无论是通过同步还是异步获取到的（同步通过API返回值获取，异步通过回调方法中的参数获取），都是同一个类的对象。该对象包装了http client原始的响应对象以及一些附加信息：

 Response response = restClient.performRequest(new Request("GET", "/"));
 RequestLine requestLine = response.getRequestLine();
 HttpHost host = response.getHost();
 int statusCode = response.getStatusLine().getStatusCode();
 Header[] headers = response.getHeaders();
 String responseBody = EntityUtils.toString(response.getEntity()); 

         如果执行请求失败的话，你将会得到一个异常，异常有以下几种：

（1）IOException：通讯问题，例如SocketTimeoutException；

（2）ResponseException：响应已经返回，但是其状态码不为2XX时将抛出这个异常。ResponseException源自于一个有效的http Response，因此该异常会将源Response暴露出来，并允许你获取它。

        注意：HEAD请求如果返回了404，ResponseException是不会被抛出的，因为对于HEAD来说资源未找到也是该方法期望的返回值之一。所有其他的HTTP方法对于404返回码都会抛出一个ResponseException，除非在ignore参数中包含了404。ignore是一个特殊的参数，该参数不会发送给es，它包含了一个分割的error status code列表。当Response的状态码在这个列表中时，它会被当成Response而不是作为Exception。对于GET方法相关的API，这是一个相当有用的特性，比如GET查询一个文档返回404，我们期望其不返回一个异常，而是一个没有document的response对象。

        注意：low-level-client并不会给出json相关的编组与解组API。你可以自由选择相关的库来进行json的编组与解组。

        底层的Apache Async Http Client库附带了不同的org.apache.http.HttpEntity实现，这些实现允许以不同的格式（流，字节数组，字符串等）提供请求主体。至于读取响应体，HttpEntity＃getContent方法很方便，它返回从先前缓冲的响应体读取的InputStream。作为替代方案，可以提供一个自定义的org.apache.http.nio.protocol.HttpAsyncResponseConsumer来控制字节的读取和缓冲方式。

 

4、通用配置

        在初始化客户端中，我们看到了RestClientBuilder支持提供一个RequestConfigCallback与一个能够用于个性化异步请求的HttpClientConfigCallback。这些回调函数能够让你在不覆盖每一个RestClient初始化默认值的情况下修改某些指定行为。本小节我们描述一些需要为low-level-client添加额外配置的公共场景。

4.1.Timeouts

        在初始化客户端的参数化设置就提过了，可以通过如下形式进行设置：

 RestClientBuilder builder = RestClient.builder(
     new HttpHost("localhost", 9200))
     .setRequestConfigCallback(
         new RestClientBuilder.RequestConfigCallback() {
             @Override
             public RequestConfig.Builder customizeRequestConfig(
                     RequestConfig.Builder requestConfigBuilder) {
                 return requestConfigBuilder
                     .setConnectTimeout(5000) //默认值1S
                     .setSocketTimeout(60000); //默认值30S
             }
         })
     .setMaxRetryTimeoutMillis(60000); //设置完SocketTimeout后，一般需要联动修改这个值

4.2.线程数

        ApacheHttpAsyncClient基于IOReactor模式，在启动时会创建一个分发线程和一组工作线程，它们由Connection Manager使用，工作线程的默认数量与能够检测到的CPU核心数一致（Runtime.getRuntime().availableProcessors()的返回结果）。可以通过如下方法修改工作线程数：

 RestClientBuilder builder = RestClient.builder(
     new HttpHost("localhost", 9200))
     .setHttpClientConfigCallback(new HttpClientConfigCallback() {
         @Override
         public HttpAsyncClientBuilder customizeHttpClient(
                 HttpAsyncClientBuilder httpClientBuilder) {
             return httpClientBuilder.setDefaultIOReactorConfig(
                 IOReactorConfig.custom()
                     .setIoThreadCount(1)
                     .build());
         }
     }); 

4.3.身份验证

        使用如下的方式设置身份验证相关的请求参数：

 final CredentialsProvider credentialsProvider =
     new BasicCredentialsProvider();
 credentialsProvider.setCredentials(AuthScope.ANY,
     new UsernamePasswordCredentials("user", "password"));

 RestClientBuilder builder = RestClient.builder(
     new HttpHost("localhost", 9200))
     .setHttpClientConfigCallback(new HttpClientConfigCallback() {
         @Override
         public HttpAsyncClientBuilder customizeHttpClient(
                 HttpAsyncClientBuilder httpClientBuilder) {
             return httpClientBuilder
                 .setDefaultCredentialsProvider(credentialsProvider);
         }
     });

        抢占式（这里翻译不太确定，结合上下文，应该指的是在第一次请求就发送身份验证信息）身份验证可以被禁用，这意味着每个HTTP请求都会在没有身份验证请求头的情况下发送，以查看它是否被接受，并且在收到HTTP 401响应后，它将使用含有身份验证请求头的报文重新发送完全相同的请求。 如果您希望这样做，那么您可以通过HttpAsyncClientBuilder禁用它：

 final CredentialsProvider credentialsProvider =
     new BasicCredentialsProvider();
 credentialsProvider.setCredentials(AuthScope.ANY,
     new UsernamePasswordCredentials("user", "password"));

 RestClientBuilder builder = RestClient.builder(
     new HttpHost("localhost", 9200))
     .setHttpClientConfigCallback(new HttpClientConfigCallback() {
         @Override
         public HttpAsyncClientBuilder customizeHttpClient(
                 HttpAsyncClientBuilder httpClientBuilder) {
             httpClientBuilder.disableAuthCaching();  /* 禁用抢占式身份验证 */
             return httpClientBuilder
                 .setDefaultCredentialsProvider(credentialsProvider);
         }
     });

4.4.SSL通信

        加密通信同样可以通过HttpClientConfigCallback进行配置。HttpAsyncClientBuilder通过3个暴露的API：setSSLContext、setSSLSessionStrategy、setConnectionManager进行加密通信的设置。下面是一个配置示例（如果没有显式配置，则会使用系统的默认配置）：

 KeyStore truststore = KeyStore.getInstance("jks");
 try (InputStream is = Files.newInputStream(keyStorePath)) {
     truststore.load(is, keyStorePass.toCharArray());
 }
 SSLContextBuilder sslBuilder = SSLContexts.custom()
     .loadTrustMaterial(truststore, null);
 final SSLContext sslContext = sslBuilder.build();
 RestClientBuilder builder = RestClient.builder(
     new HttpHost("localhost", 9200, "https"))
     .setHttpClientConfigCallback(new HttpClientConfigCallback() {
         @Override
         public HttpAsyncClientBuilder customizeHttpClient(
                 HttpAsyncClientBuilder httpClientBuilder) {
             return httpClientBuilder.setSSLContext(sslContext);
         }
     });

4.5.节点选择器

        客户端默认情况下会以轮询的形式将请求发送到每一个初始化时配置的节点上。在初始化时，我们可以提供一个节点选择器NodeSelector。当嗅探开启时这个功能会很好用，以防只有HTTP请求才能访问专用主节点。 对于每个请求，客户端将运行最终配置的节点选择器以过滤候选节点，然后从列表中选择下一个节点选择器。下面是一个基于机架进行节点选择的例子：

 RestClientBuilder builder = RestClient.builder(
         new HttpHost("localhost", 9200, "http"));
 builder.setNodeSelector(new NodeSelector() {
     @Override
     public void select(Iterable<Node> nodes) {
         /*
          * Prefer any node that belongs to rack_one. If none is around
          * we will go to another rack till it's time to try and revive
          * some of the nodes that belong to rack_one.
          */
         boolean foundOne = false;
         for (Node node : nodes) {
             String rackId = node.getAttributes().get("rack_id").get(0);
             if ("rack_one".equals(rackId)) {
                 foundOne = true;
                 break;
             }
         }
         if (foundOne) {
             Iterator<Node> nodesIt = nodes.iterator();
             while (nodesIt.hasNext()) {
                 Node node = nodesIt.next();
                 String rackId = node.getAttributes().get("rack_id").get(0);
                 if ("rack_one".equals(rackId) == false) {
                     nodesIt.remove();
                 }
             }
         }
     }
 });

        上面的例子中，优先选择一号机架上的节点。当一号机架没有任何节点时，才会选择其他机架节点。

       需要注意的是，如果一个NodeSelector无法提供一个始终如一的（或者说稳定的）节点列表，那么轮询发送请求至不同node的行为将会变得不可预测或失效。在上面的例子中，轮询行为会很好的工作，因为这个例子中的代码可以很好的（或比较稳定的）获取到哪些结点可用（这些获取到的可用结点能够影响轮询行为的可预测性）。因此，这也提醒我们NodeSelector不应该依赖于任何外部因素，否则轮询行为将会变的不可预测。

 

5、嗅探Sniffer

        允许从一个运行的ES集群中自动发现结点，并且将发现的结点设置入一个已存在的RestClient。默认的，它使用节点信息api检索属于集群的节点，并使用jackson解析获得的json响应。

        要使用该功能，必须引入依赖，该依赖版本同rest-client版本一样，跟着es的发布版本走的：

 <dependency>
     <groupId>org.elasticsearch.client</groupId>
     <artifactId>elasticsearch-rest-client-sniffer</artifactId>
     <version>6.5.4</version>
 </dependency>

5.1.基本设置

        在初始化的RestClient的时候将一个Sniffer与其进行关联。Sniffer嗅探器会为RestClient提供一个周期性的拉取es所有结点列表的功能（默认5分钟拉取一次），拉取到节点列表后，会调用RestClient.setNodes的API将其更新入RestClient。

 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200, "http"))
     .build();
 Sniffer sniffer = Sniffer.builder(restClient).build(); 

        Sniffer应该具有同RestClient一样的生命周期，也就是说，在关闭RestClient时，也需要关闭Sniffer以释放其占用的资源：

 sniffer.close();
 restClient.close(); 

5.2.定制刷新间隔

        上面我们提到了，Sniffer默认5分钟刷新一次，我们可以在初始化Sniffer的时候改变这个时间（单为：毫秒）：

 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200, "http"))
     .build();
 Sniffer sniffer = Sniffer.builder(restClient)
     .setSniffIntervalMillis(60000).build(); //设置Sniffer刷新间隔

        另外，我们可以在请求失败上启用Sniffer，即在每次请求节点失败后，可以让Sniffer执行一次节点更新（区别于Sniffer固定间隔的刷新）。我们需要为RestClient提供一个SnifferOnFailureListener，并在Client初始化的时候设置这个监听器，同时在创建Sniffer之后也需要将其设置给这个监听器。这样一来，每次失败之后，监听器监听到失败就会委托Sniffer去执行节点刷新：

 SniffOnFailureListener sniffOnFailureListener =
     new SniffOnFailureListener(); //创建Sniffer失败监听器
 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200))
     .setFailureListener(sniffOnFailureListener) //为RestClient设置监听器
     .build();
 Sniffer sniffer = Sniffer.builder(restClient)
     .setSniffAfterFailureDelayMillis(30000) //设置失败之后的额外调度延迟
     .build();
 sniffOnFailureListener.setSniffer(sniffer); //为监听器设置Sniffer

• 关于setSniffAfterFailureDelayMillis：当我们在失败上设置了Sniffer监听后，每次失败不仅会通过监听器勾起一次Sniffer的节点刷新行为，一次额外的Sniffer节点刷新行为也会比平常的间隔调度更快的到来（这是Sniffer的默认特征，且默认时间为1分钟）。假设失败的节点能够很快的恢复，我们的应用需要尽快知道这个情况，那么我们可以通过setSniffAfterFailureDelayMillis来调整这个额外Sniffer行为的延迟时间（这是什么意思呢？举个例子，当请求失败后，通过监听器触发的Sniffer行为获取到的节点列表可能是剔除了有问题节点的列表，如果此时问题节点未恢复的话；可能这些问题节点在一阵子后自行恢复了，但是Sniffer还没有到下次触发时间，因此我们需要调整一下这个失败后Sniffer额外调度的延迟时间，缩短该时间以尽快拉取到恢复后的节点列表）。

5.3.设置节点通信协议

        Sniffer的节点列表刷新行为使用的是NodeInfo API，这个API只能返回节点的IP和PORT信息，对于连接节点使用到的协议无法返回，因此默认认为节点通信使用的是HTTP协议。在使用HTTPS协议的情况下，我们需要手工的设置一个ElasticsearchNodesSniffer实例用来告知Sniffer节点通信的协议是HTTPS：

 RestClient restClient = RestClient.builder(
         new HttpHost("localhost", 9200, "http"))
         .build();
 NodesSniffer nodesSniffer = new ElasticsearchNodesSniffer(
         restClient,
         ElasticsearchNodesSniffer.DEFAULT_SNIFF_REQUEST_TIMEOUT,
         ElasticsearchNodesSniffer.Scheme.HTTPS);
 Sniffer sniffer = Sniffer.builder(restClient)
         .setNodesSniffer(nodesSniffer).build();

        通过同样的方式，我们可以设置SnifferRequestTimeout这个参数的值（默认1S）。当调用NodeInfoAPI时，这个超时参数会作为查询字符串中的参数，它告诉ES服务器查询节点列表的超时时间。因此当服务器侧出现超时的时候仍然会返回一个有效的响应结果（服务器侧查询节点列表的超时，不代表Sniffer请求自身的超时），这个响应结果可能只包含节点列表的一个子集，即在超时时间内能获取到的节点列表数据：

 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200, "http"))
     .build();
 NodesSniffer nodesSniffer = new ElasticsearchNodesSniffer(
     restClient,
     TimeUnit.SECONDS.toMillis(5),
     ElasticsearchNodesSniffer.Scheme.HTTP);
 Sniffer sniffer = Sniffer.builder(restClient)
     .setNodesSniffer(nodesSniffer).build(); 

5.4.自定义NodesSniffer

        有时候，我们需要自定义一个NodesSniffer完成一些个性化的特殊功能，比如从一个内部资源中获取节点列表（如文件）而不是从ES服务器集群中获取节点列表：

 RestClient restClient = RestClient.builder(
     new HttpHost("localhost", 9200, "http"))
     .build();
 NodesSniffer nodesSniffer = new NodesSniffer() {
         @Override
         public List<Node> sniff() throws IOException {
             return null;
         }
     };
 Sniffer sniffer = Sniffer.builder(restClient)
     .setNodesSniffer(nodesSniffer).build();