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’ssuspendCancellableCoRoutine之類的框架一起使用。取消不再需要的請求是避免對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();