« 安装 从高级 REST 客户端迁移 »
Elastic 文档 ›Elasticsearch Java API 客户端 [8.17] ›设置

连接

编辑

连接

编辑

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

  • API 客户端类。 这些为 Elasticsearch API 提供了强类型的数据结构和方法。由于 Elasticsearch API 非常庞大，它被组织成功能组（也称为“命名空间”），每个功能组都有自己的客户端类。 Elasticsearch 核心功能在 ElasticsearchClient 类中实现。
  • 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 客户端管理。有关配置身份验证的更多详细信息，请参阅 其文档。

您的第一个请求

编辑

下面的代码片段从名称与“bicycle”匹配的 “product” 索引中搜索所有项目，并将它们作为 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 客户端以使用 HTTPS 和生成的 CA 证书，以便成功发出请求。

当您首次启动 Elasticsearch 时，您会在 Elasticsearch 的输出中看到一个如下所示的独特代码块（如果已经过了一段时间，您可能需要向上滚动）

-> 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 指纹，以便在接下来的章节中使用。在下面的示例中，它们将分别存储在变量 password 和 fingerprint 中。

根据上下文，您有两种选择来验证 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 客户端测试中找到。

« 安装 从高级 REST 客户端迁移 »