ElasticSearch学习笔记

ElasticSearch版本： Java Rest Client 7.8 （此笔记为翻译版）

原文：https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-low-usage-requests.html 

Maven 依赖：

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

 

基本使用

主要使用的类及接口：

　　RestClient ：线程安全，理想情况下与使用它的应用程序具有相同的生命周期。内部由RestClientBuilder类实例化RestClient实例的。

　　　　　　例如：

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

 

 重要的是，在不再需要它时将其关闭，以便正确释放其使用的所有资源以及基础的HTTP客户端实例及其线程：

restClient.close();

 

RestClientBuilder还允许在构建RestClient实例时有选择地设置以下配置参数：

RestClientBuilder builder = RestClient.builder(
    new HttpHost("localhost", 9200, "http"));
Header[] defaultHeaders = new Header[]{new BasicHeader("header", "value")};
builder.setDefaultHeaders(defaultHeaders);  // 设置每个请求都需要发送的默认标头，以防止必须在每个单个请求中指定它们

 

RestClientBuilder builder = RestClient.builder(
        new HttpHost("localhost", 9200, "http"));
builder.setFailureListener(new RestClient.FailureListener() {
    @Override
    public void onFailure(Node node) {
        //设置一个侦听器，该侦听器在每次节点发生故障时得到通知，以防需要采取措施。启用sniffing失败时在内部使用。
    }
});

 

RestClientBuilder builder = RestClient.builder(
    new HttpHost("localhost", 9200, "http"));
builder.setNodeSelector(NodeSelector.SKIP_DEDICATED_MASTERS); // 设置节点选择器以用于过滤客户端将向其自身设置的请求中的客户端发送请求的节点。 例如，在启用嗅探功能时，这可以防止阻止向专用主节点发送请求。 默认情况下，客户端将请求发送到每个已配置的节点。

 

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);  // 设置允许修改默认请求配置的回调（例如，请求超时，身份验证或org.apache.http.client.config.RequestConfig.Builder允许设置的任何内容）
        }
    });

 

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"));  //设置允许修改http客户端配置的回调（例如，通过ssl加密的通信，或org.apache.http.impl.nio.client.HttpAsyncClientBuilder允许设置的任何内容）
        }
    });

 

 

配置执行请求

一旦创建RestClient，就可以通过调用performRequest或performRequestAsync发送请求。performRequest是同步的，将阻塞调用线程并在请求成功时返回响应，如果请求失败则抛出异常。performRequestAsync是异步的，接受一个ResponseListener参数，该参数在请求成功时以Response调用，如果失败则以Exception调用。

 

同步代码示例：

Request request = new Request(
    "GET",  // HTTP方法（GET，POST，HEAD等）
    "/");    // 服务器上的端点
Response response = restClient.performRequest(request);

异步代码示例：

Request request = new Request(
    "GET",  //HTTP方法（GET，POST，HEAD等）
    "/");     // 服务器上的端点
Cancellable cancellable = restClient.performRequestAsync(request,
    new ResponseListener() {
        @Override
        public void onSuccess(Response response) {
            // 处理执行成功的响应
        }

        @Override
        public void onFailure(Exception exception) {
              // 处理故障
        }
});

 

您可以将请求参数添加到请求对象：

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

您可以将请求的主体设置为任何HttpEntity：

request.setEntity(new NStringEntity(
        "{\"json\":\"text\"}",   //请求json内容
        ContentType.APPLICATION_JSON)  //内容类型
);
// 为HttpEntity指定的ContentType很重要，因为它将用于设置Content-Type标头，以便Elasticsearch可以正确解析内容。

您还可以将其设置为String，该字符串将默认为application/json的ContentType。

request.setJsonEntity("{\"json\":\"text\"}");

 

2.1 请求选项

RequestOptions类保存应在同一应用程序中的许多请求之间共享的部分请求。您可以创建一个单例实例，并在所有请求之间共享它：

private static final RequestOptions COMMON_OPTIONS;
static {
    RequestOptions.Builder builder = RequestOptions.DEFAULT.toBuilder();
    builder.addHeader("Authorization", "Bearer " + TOKEN);  // 添加所有请求所需的任何标头
    builder.setHttpAsyncResponseConsumerFactory(        // 自定义响应使用者。   
        new HttpAsyncResponseConsumerFactory
            .HeapBufferedResponseConsumerFactory(30 * 1024 * 1024 * 1024));
    COMMON_OPTIONS = builder.build();
}

addHeader用于授权或与Elasticsearch前面的代理一起使用所需的标头。无需设置Content-Type标头，因为客户端将根据附加到请求的HttpEntity自动设置标头。

您可以设置NodeSelector来控制哪些节点将接收请求。NodeSelector.NOT_MASTER_ONLY是一个不错的选择。

您还可以自定义用于缓冲异步响应的响应使用者。默认使用者将在JVM堆上最多缓冲100MB的响应。如果响应较大，则请求将失败。例如，您可以降低最大大小，如果在上面示例中的堆受限环境中运行，则可能会很有用。

创建单例后，可以在提出请求时使用它：

request.setOptions(COMMON_OPTIONS);
// 您还可以根据每个请求自定义这些选项。例如，这添加了一个额外的header：
RequestOptions.Builder options = COMMON_OPTIONS.toBuilder();
options.addHeader("cats", "knock things off of other things");
request.setOptions(options);

 

 多个并行异步操作

Client很高兴并行执行许多动作。下面的示例并行索引许多文档。在现实世界中，您可能想改用_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);
    //假设文档存储在HttpEntity数组中
    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();

 

取消异步操作

performRequestAsync方法返回一个Cancellable，它公开了一个称为cancel的公共方法。可以调用这种方法来取消正在进行的请求。取消请求将导致通过基础的HTTP客户端中止HTTP请求。在服务器端，这不会自动转换为取消该请求的执行，而这需要在API本身中专门实现。

Cancellable 实例的使用是可选的，如果不需要，您可以放心地忽略它。一个典型的用例是将其与Rx Java或 Kotlin’s suspendCancellableCoRoutine之类的框架一起使用。取消不再需要的请求是避免对Elasticsearch施加不必要负载的好方法。

Request request = new Request("GET", "/posts/_search");
Cancellable cancellable = restClient.performRequestAsync(
    request,
    new ResponseListener() {
        @Override
        public void onSuccess(Response response) {
            // 处理返回的响应，以防在取消请求之前已准备好
        }

        @Override
        public void onFailure(Exception exception) {
            // 处理返回的异常，当请求被取消时，很有可能是CancellationException
        }
    }
);
cancellable.cancel();