连接

编辑

Java API 客户端围绕三个主要组件构建

  • API 客户端类。这些类提供 Elasticsearch API 的强类型数据结构和方法。由于 Elasticsearch API 非常庞大,它被组织成功能组(也称为“命名空间”),每个功能组都有其自己的客户端类。ElasticsearchClient 类实现了 Elasticsearch 的核心功能。
  • JSON 对象映射器。它将您的应用程序类映射到 JSON,并与 API 客户端无缝集成。
  • 传输层实现。所有 HTTP 请求处理都在此处进行。

此代码片段创建并连接了这三个组件

// URL and API key
String serverUrl = "https://127.0.0.1:9200";
String apiKey = "VnVhQ2ZHY0JDZGJrU...";

// Create the low-level client
RestClient restClient = RestClient
    .builder(HttpHost.create(serverUrl))
    .setDefaultHeaders(new Header[]{
        new BasicHeader("Authorization", "ApiKey " + apiKey)
    })
    .build();

// Create the transport with a Jackson mapper
ElasticsearchTransport transport = new RestClientTransport(
    restClient, new JacksonJsonpMapper());

// And create the API client
ElasticsearchClient esClient = new ElasticsearchClient(transport);

// Use the client...

// Close the client, also closing the underlying transport object and network connections.
esClient.close();

身份验证由Java 低级 REST 客户端管理。有关配置身份验证的更多详细信息,请参阅其文档

您的第一个请求

编辑

下面的代码片段搜索“product”索引中名称匹配“bicycle”的所有项,并将它们作为Product应用程序类的实例返回。

它演示了如何使用流畅的功能构建器将搜索查询编写为简洁的 DSL 式代码。此模式在API 约定中进行了更详细的解释。

SearchResponse<Product> search = esClient.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());
}

使用安全连接

编辑

Java 低级 REST 客户端文档详细解释了如何设置加密通信。

在自管理安装中,Elasticsearch 将启用身份验证和 TLS 等安全功能。要连接到 Elasticsearch 集群,您需要配置 Java API 客户端以使用生成的 CA 证书通过 HTTPS 进行请求。

首次启动 Elasticsearch 时,您将在 Elasticsearch 的输出中看到如下所示的 distinct 块(如果过了一段时间,您可能需要向上滚动)

-> 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
...

记下 elastic 用户密码和 HTTP CA 指纹以备后续章节使用。在下面的示例中,它们将分别存储在变量passwordfingerprint中。

根据具体情况,您可以通过两种方式验证 HTTPS 连接:使用 CA 证书本身进行验证或使用 CA 证书指纹进行验证。对于这两种情况,Java API 客户端的TransportUtils类都提供了方便的方法来轻松创建SSLContext

使用证书指纹验证 HTTPS
编辑

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

String fingerprint = "<certificate fingerprint>";

SSLContext sslContext = TransportUtils
    .sslContextFromCaFingerprint(fingerprint); 

BasicCredentialsProvider credsProv = new BasicCredentialsProvider(); 
credsProv.setCredentials(
    AuthScope.ANY, new UsernamePasswordCredentials(login, password)
);

RestClient restClient = RestClient
    .builder(new HttpHost(host, port, "https")) 
    .setHttpClientConfigCallback(hc -> hc
        .setSSLContext(sslContext) 
        .setDefaultCredentialsProvider(credsProv)
    )
    .build();

// Create the transport and the API client
ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
ElasticsearchClient esClient = new ElasticsearchClient(transport);

// Use the client...

// Close the client, also closing the underlying transport object and network connections.
esClient.close();

使用证书指纹创建SSLContext

设置身份验证。

不要忘记将协议设置为https

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

请注意,也可以使用openssl x509和证书文件计算证书指纹

openssl x509 -fingerprint -sha256 -noout -in /path/to/http_ca.crt

如果您无法访问 Elasticsearch 生成的 CA 文件,可以使用以下脚本使用openssl s_client输出 Elasticsearch 实例的根 CA 指纹

openssl s_client -connect localhost:9200 -servername localhost -showcerts </dev/null 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout -in /dev/stdin
使用 CA 证书验证 HTTPS
编辑

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

使http_ca.crt文件可供您的应用程序使用后,您可以使用它来设置客户端

File certFile = new File("/path/to/http_ca.crt");

SSLContext sslContext = TransportUtils
    .sslContextFromHttpCaCrt(certFile); 

BasicCredentialsProvider credsProv = new BasicCredentialsProvider(); 
credsProv.setCredentials(
    AuthScope.ANY, new UsernamePasswordCredentials(login, password)
);

RestClient restClient = RestClient
    .builder(new HttpHost(host, port, "https")) 
    .setHttpClientConfigCallback(hc -> hc
        .setSSLContext(sslContext) 
        .setDefaultCredentialsProvider(credsProv)
    )
    .build();

// Create the transport and the API client
ElasticsearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
ElasticsearchClient esClient = new ElasticsearchClient(transport);

// Use the client...

// Close the client, also closing the underlying transport object and network connections.
esClient.close();

使用http_ca.crt文件创建SSLContext

设置身份验证。

不要忘记将协议设置为https

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

上述示例的源代码可以在Java API 客户端测试中找到。