文章目录

  • 兼容性
  • Javadoc
  • Maven 资源库
  • Maven 配置
  • Gradle 配置
  • Lucene 快照存储库
  • 依赖
  • 初始化
  • RequestOptions
  • 使用异步



官方文档地址：

Getting started

本节描述如何开始使用高级 REST 客户端，从获取工件到在应用程序中使用它。

兼容性

Java 高级 REST 客户端至少需要 Java 1.8，并且依赖于 Elasticsearch 核心项目。客户端版本要与 Elasticsearch 版本相同。它接受与TransportClient相同的请求参数，并返回相同的响应对象。如果需要将应用程序从TransportClient迁移到新的 REST 客户端，请参阅迁移指南。

高级客户端保证能够与运行在相同主版本和更大或相等的小版本上的任何 Elasticsearch 节点通信。它不需要与需要通信的 Elasticsearch 节点处于相同的小版本中，因为它是向前兼容的，这意味着它支持与 Elasticsearch 的新版本通信，而不是开发它的目的版本。

6.0 客户端能够与任何 6.x Elasticsearch 节点通信，而 6.1 客户端肯定能够与 6.1、6.2 以及任何更高版本的 6.x Elasticsearch 节点通信。但是当与以前版本的 Elasticsearch 节点通信时，可能会出现不兼容的问题，例如在 6.1 和 6.0 之间，如果 6.1 客户端支持一些 API 的新请求体字段，而 6.0 节点不知道这些字段。

建议升级高级客户端当 Elasticsearch 集群升级到一个新的主版本，作为 REST API 的变化可能会导致意想不到的结果，因为新版本的客户端才会支持新版本节点新添加的 API。一旦集群中的所有节点都升级到新的主版本，客户端应该总是最后更新。

Javadoc

用于 REST 高级客户端的 javadoc 可以在https://artifacts.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-high-level-client/7.14.1/index.html找到。

Maven 资源库

Java 高级 REST 客户端驻留在 Maven Central 上。所需的最低 Java 版本是 1.8。

高级 REST 客户端与 Elasticsearch 遵循相同的发布周期。将版本替换为所需的客户端版本。

如果你正在寻找快照版本，你应该将我们的快照存储库添加到 Maven 配置中：

<repositories>
    <repository>
        <id>es-snapshots</id>
        <name>elasticsearch snapshot repo</name>
        <url>https://snapshots.elastic.co/maven/</url>
    </repository>
</repositories>

或者在 Gradle：

maven {
        url "https://snapshots.elastic.co/maven/"
}

Maven 配置

下面介绍如何使用 Maven 作为依赖项管理器来配置依赖项。在pom.xml文件中添加以下内容：

<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.14.1</version>
</dependency>

Gradle 配置

下面是如何使用 Gradle 作为依赖管理器来配置依赖项。将以下内容添加到构建中build.gradle文件：

dependencies {
    compile 'org.elasticsearch.client:elasticsearch-rest-high-level-client:7.14.1'
}

Lucene 快照存储库

任何主要版本（比如 beta 版）的第一个版本都可能是建立在 Lucene 快照版本之上的。在这种情况下，您将无法解决客户端的Lucene 依赖关系。

例如，如果您想使用依赖于 Lucene 8.0.0-snapshot-83f9835的7.0.0-beta1版本，则必须定义以下存储库。

Maven：

<repository>
    <id>elastic-lucene-snapshots</id>
    <name>Elastic Lucene Snapshots</name>
    <url>https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/83f9835</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>false</enabled></snapshots>
</repository>

Gradle：

maven {
    name 'lucene-snapshots'
    url 'https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/83f9835'
}

依赖

高级 Java REST 客户端依赖于以下工件及其传递依赖关系：

  • org.elasticsearch.client:elasticsearch-rest-client
  • org.elasticsearch:elasticsearch

初始化

一个RestHighLevelClient实例需要一个 REST 低级客户端构建器，如下所示：

RestHighLevelClient client = new RestHighLevelClient(
        RestClient.builder(
                new HttpHost("localhost", 9200, "http"),
                new HttpHost("localhost", 9201, "http")));

高级客户端将在内部基于提供的构建器创建用于执行请求的低级客户端。低级客户端维护一个连接池，并启动一些线程，所以当你真正完成时，你应该关闭高级客户端，它会反过来关闭内部低级客户端以释放那些资源。这可以通过close关闭：

client.close();

在本文档关于 Java 高级客户机的其余部分中，RestHighLevelClient实例将作为client引用。

RequestOptions

RestHighLevelClient中的所有 API 都接受一个RequestOptions，您可以使用它来定制请求，而不会改变 Elasticsearch 执行请求的方式。例如，在这里可以指定一个NodeSelector来控制哪个节点接收请求。有关自定义选项的更多示例，请参阅低级客户端文档。

使用异步

跨不同客户端的所有方法都存在于传统的同步和异步变体中。不同之处在于异步请求在 REST 低级客户端中使用异步请求发起。如果你正在处理多个请求，或者正在使用 rx java、Kotlin co-routines 或类似的框架，这是非常有用的。

异步方法是可以识别的，因为它们的名称中有“Async”这个词，并返回一个Cancellable实例。异步方法接受与同步变量相同的请求对象，并接受通用的ActionListener<T>，其中T是同步方法的返回类型。

所有异步方法都返回一个带有cancel方法的Cancellable对象，您可以在想要中止请求时调用该方法。取消不再需要的请求是避免给 Elasticsearch 带来不必要负载的好方法。

使用Cancellable实例是可选的，如果不需要，可以忽略它。这方面的一个用例是与 Kotlin 的 suspendCancellableCoRoutine一起使用。