Elasticsearch教程—Elasticsearch Java API Client [8.6]开发入门（官方原版）

大家好,我是Doker！

一、开发要求：

• Java 8 或更高版本。

• 一个 JSON 对象映射库，允许无缝集成 您的应用程序类与 Elasticsearch API 一起。Java 客户端具有 支持 Jackson 或 Eclipse Yasson 等 JSON-B 库。

二、开发实例

1、在项目的pom.xml中，添加以下存储库定义和依赖项：

<dependencies>
 
    <dependency>
      <groupId>co.elastic.clients</groupId>
      <artifactId>elasticsearch-java</artifactId>
      <version>8.6.2</version>
    </dependency>
 
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.12.3</version>
    </dependency>
 
  </dependencies>

2、连接

Java API客户端由三个主要组件组成：

• API客户端类。这些为Elasticsearch API提供了强类型的数据结构和方法。由于Elasticsearch API很大，所以它是按功能组（也称为“名称空间”）构建的，每个功能组都有自己的客户端类。Elasticsearch核心功能在ElasticearchClient类中实现。

• JSON对象映射器。这将应用程序类映射到JSON，并将它们与API客户端无缝集成。

• 传输层实现。这是所有HTTP请求处理的地方。

此代码段创建并连接以下三个组件：

// Create the low-level client
RestClient restClient = RestClient.builder(
    new HttpHost("localhost", 9200)).build();
 
// Create the transport with a Jackson mapper
ElasticsearchTransport transport = new RestClientTransport(
    restClient, new JacksonJsonpMapper());
 
// And create the API client
ElasticsearchClient client = new ElasticsearchClient(transport);

查询代码：

SearchResponse<Product> search = client.search(s -> s
    .index("products")
    .query(q -> q
        .term(t -> t
            .field("name")
            .value(v -> v.stringValue("bicycle"))
        )),
    Product.class);
 
for (Hit<Product> hit: search.hits().hits()) {
    processProduct(hit.source());
}

使用安全连接

在自行安装时，Elasticsearch 将从启用身份验证和 TLS 等安全功能开始。要连接到 Elasticsearch 集群，您需要将 Java API 客户端配置为将 HTTPS 与生成的 CA 证书一起使用，以便成功发出请求。

当你第一次启动Elasticsearch时，你会在Elasticearch的输出中看到一个不同的块，如下图所示（如果有一段时间，你可能需要向上滚动）：

-> Elasticsearch security features have been automatically configured!
-> Authentication is enabled and cluster connections are encrypted.
 
->  Password for the elastic user (reset with `bin/elasticsearch-reset-password -u elastic`):
  lhQpLELkjkrawaBoaz0Q
 
->  HTTP CA certificate SHA-256 fingerprint:
  a52dd93511e8c6045e21f16654b77c9ee0f34aea26d9f40320b531c474676228
...

记下弹性用户密码和HTTP CA指纹，以供下一节使用。在下面的示例中，它们将分别存储在变量password和fingerprint中。

根据上下文，您有两个验证HTTPS连接的选项：使用CA证书本身验证或使用CA证书指纹验证。对于这两种情况，JavaAPI客户端的TransportUtils类提供了方便的方法来轻松创建SSLContext。

使用证书指纹验证 HTTPS

这种验证 HTTPS 连接的方法使用前面记下的证书指纹值。

String fingerprint = "<certificate fingerprint>";
 
SSLContext sslContext = TransportUtils
    .sslContextFromCaFingerprint(fingerprint); （1）
 
BasicCredentialsProvider credsProv = new BasicCredentialsProvider(); （2）
credsProv.setCredentials(
    AuthScope.ANY, new UsernamePasswordCredentials(login, password)
);
 
RestClient restClient = RestClient
    .builder(new HttpHost(host, port, "https")) （3）
    .setHttpClientConfigCallback(hc -> hc
        .setSSLContext(sslContext) （4）
        .setDefaultCredentialsProvider(credsProv)
    )
    .build();
 
// Create the transport and the API client
ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
ElasticsearchClient client = new ElasticsearchClient(transport);

（1）使用证书指纹创建SSLContext。

（2）设置身份验证。

（3）不要忘记将协议设置为https！

（4）使用SSL和身份验证配置配置http客户端。

使用CA证书验证HTTPS编辑

生成的根CA证书可以在Elasticsearch配置位置的certs目录中找到。如果您在Docker中运行Elasticsearch，则有其他文档可用于检索CA证书。

一旦应用程序可以使用http_c.crt文件，就可以使用它来设置客户端：

File certFile = new File("/path/to/http_ca.crt");
 
SSLContext sslContext = TransportUtils
    .sslContextFromHttpCaCrt(certFile); (1)
 
BasicCredentialsProvider credsProv = new BasicCredentialsProvider(); (2)
credsProv.setCredentials(
    AuthScope.ANY, new UsernamePasswordCredentials(login, password)
);
 
RestClient restClient = RestClient
    .builder(new HttpHost(host, port, "https")) (3)
    .setHttpClientConfigCallback(hc -> hc
        .setSSLContext(sslContext) (4)
        .setDefaultCredentialsProvider(credsProv)
    )
    .build();
 
// Create the transport and the API client
ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
ElasticsearchClient client = new ElasticsearchClient(transport);

(1)使用http_c.crt文件创建SSLContext。

(2)设置身份验证。

(3)不要忘记将协议设置为https！

(4)使用SSL和身份验证配置配置http客户端。

3、包构和命名空间客户端

Elasticsearch API 很大，并且被组织成功能

Java API客户端遵循这样的结构：功能组称为“命名空间”，每个命名空间都位于co.elastic.clients.elasticsearch的子包中。

每个命名空间客户端都可以从顶级Elasticsearch客户端访问。唯一的例外是“搜索”和“文档”API，它们位于核心子包中，可以在主要的Elasticsearch客户端对象上访问。

下面的代码片段显示了如何使用indexs命名空间客户端创建索引（lambda语法在构建API对象中进行了解释）：

ElasticsearchClient client = ...
client.indices().create(c -> c.index("products"));

4、方法命名约定

Java API 客户机中的类包含两种方法和属性：

• 作为API一部分的方法和财产，例如ElasticsearchClient.search（）或SearchResponse.maxScore（）。它们是使用标准Java camelCaseNaming约定从Elasticsearch JSON API中各自的名称派生而来的。

• 方法和财产是构建Java API客户端的框架的一部分，例如Query_kind（）。这些方法和财产以下划线作为前缀，既可以避免与API名称发生任何命名冲突，也可以方便地将API与框架区分开来。

5、阻塞和异步客户端

API客户端有两种类型：阻塞和异步。异步客户端上的所有方法都返回标准的CompletableFuture。

根据您的需要，两种口味可以同时使用，共享相同的传输对象：

ElasticsearchTransport transport = ...
 
// Synchronous blocking client
ElasticsearchClient client = new ElasticsearchClient(transport);
 
if (client.exists(b -> b.index("products").id("foo")).value()) {
    logger.info("product exists");
}
 
// Asynchronous non-blocking client
ElasticsearchAsyncClient asyncClient =
    new ElasticsearchAsyncClient(transport);
 
asyncClient
    .exists(b -> b.index("products").id("foo"))
    .whenComplete((response, exception) -> {
        if (exception != null) {
            logger.error("Failed to index", exception);
        } else {
            logger.info("Product exists");
        }
    });

6、构建 API 对象

生成器对象

Java API 客户机中的所有数据类型都是不可变的。对象创建使用2008年在Effective Java中流行的构建器模式。

ElasticsearchClient client = ...
CreateIndexResponse createResponse = client.indices().create(
    new CreateIndexRequest.Builder()
        .index("my-index")
        .aliases("foo",
            new Alias.Builder().isWriteIndex(true).build()
        )
        .build()
);

请注意，生成器在其build（）方法被调用后不应被重用。

生成器 lambda 表达式

虽然这很好，但必须实例化生成器类并调用build（）方法有点冗长。因此，JavaAPIClient中的每个属性设置器都接受一个lambda表达式，该表达式将新创建的构建器作为参数，并返回一个填充的构建器。上面的代码段也可以写成：

ElasticsearchClient client = ...
CreateIndexResponse createResponse = client.indices()
    .create(createIndexBuilder -> createIndexBuilder
        .index("my-index")
        .aliases("foo", aliasBuilder -> aliasBuilder
            .isWriteIndex(true)
        )
    );

这种方法允许更简洁的代码，并且还避免了导入 类（甚至记住它们的名字），因为类型是从 方法参数签名。

请注意，在上面的示例中，构建器变量仅用于启动链 的财产设置者。因此，这些变量的名称并不重要，并且 可以缩短以提高可读性：

ElasticsearchClient client = ...
CreateIndexResponse createResponse = client.indices()
    .create(c -> c
        .index("my-index")
        .aliases("foo", a -> a
            .isWriteIndex(true)
        )
    );

生成器lambdas对于下面这样的复杂嵌套查询特别有用，这些查询取自interval查询API文档。

本示例还强调了深度嵌套结构中生成器参数的一个有用的命名约定。对于带有单个参数的lambda表达式，Kotlin提供了隐式it参数，Scala允许使用_。这可以在Java中通过使用下划线或单个字母前缀，后跟表示深度级别的数字（即_0、_1或b0、b1等）来近似。这不仅消除了创建一次性变量名的需要，而且还提高了代码的可读性。正确的缩进还可以使查询的结构突出。

ElasticsearchClient client = ...
SearchResponse<SomeApplicationData> results = client
    .search(b0 -> b0
        .query(b1 -> b1
            .intervals(b2 -> b2
                .field("my_text")
                .allOf(b3 -> b3
                    .ordered(true)
                    .intervals(b4 -> b4
                        .match(b5 -> b5
                            .query("my favorite food")
                            .maxGaps(0)
                            .ordered(true)
                        )
                    )
                    .intervals(b4 -> b4
                        .anyOf(b5 -> b5
                            .intervals(b6 -> b6
                                .match(b7 -> b7
                                    .query("hot water")
                                )
                            )
                            .intervals(b6 -> b6
                                .match(b7 -> b7
                                    .query("cold porridge")
                                )
 
                            )
                        )
                    )
                )
            )
        ),
    SomeApplicationData.class 
);

7、变量类型

Elasticsearch API有很多变体类型：查询、聚合、字段映射、分析器等等。在这样大的集合中找到正确的类名可能很困难。

JavaAPI客户端构建器使这一点变得简单：变量类型（如Query）的构建器为每个可用实现提供了方法。我们已经在上面的操作中看到了间隔（一种查询）和allOf、match和anyOf（各种间隔）。

这是因为JavaAPI客户端中的变量对象是“标记联合”的实现：它们包含所持有的变量的标识符（或标记）和该变量的值。例如，Query对象可以包含带标记间隔的IntervalsQuery、带标记项的TermQuery等。这种方法允许编写流畅的代码，让IDE完成功能指导您构建和导航复杂的嵌套结构：

变量生成器为每个可用的实现提供setter方法。它们使用与常规财产相同的约定，并接受生成器lambda表达式和实际变量类型的现成对象。下面是一个构建术语查询的示例：

Query query = new Query.Builder()
    .term(t -> t                 （1）         
        .field("name")           （2）       
        .value(v -> v.stringValue("foo"))
    )
    .build();                    （3）

（1）选择术语变体以构建术语查询。

（2）使用生成器lambda表达式生成术语查询。

（3）构建现在保存一个TermQuery对象的查询。

Elasticsearch教程— Java API Client[8.6] 开发入门2（官方原版）