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

连接

编辑

连接编辑

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);

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

您的第一个请求编辑

以下代码段搜索“产品”索引中名称与“自行车”匹配的所有项目，并将它们作为 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 client = new ElasticsearchClient(transport);

使用证书指纹创建 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 client = new ElasticsearchClient(transport);

使用 http_ca.crt 文件创建 SSLContext。

设置身份验证。

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

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

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

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