连接
编辑连接编辑
本页面包含连接和使用 Elasticsearch 客户端所需的信息。
本页内容
身份验证编辑
本文档包含代码片段，向您展示如何连接到各种 Elasticsearch 提供程序。
Elastic Cloud编辑
如果您使用的是 Elastic Cloud，则客户端提供了一种简单的方法来连接到它。您需要在云控制台中找到的 Cloud ID，以及您的用户名和密码。
收集 Cloud ID 后，您可以使用客户端连接到您的 Elastic Cloud 实例，如下所示
require 'elasticsearch' client = Elasticsearch::Client.new( cloud_id: '<CloudID>' user: '<Username>', password: '<Password>', )
您还可以使用 API 密钥身份验证连接到云。您可以在 安全 部分下的 管理 页面中生成 API 密钥。
单击 创建 API 密钥 时，您可以选择名称并设置其他选项（例如，限制权限、过期时间等）。
完成此步骤后，您将在 API 密钥页面中获得 API 密钥。
重要提示：您需要将 API 密钥 复制并存储在安全的地方，因为您将无法在 Elastic Cloud 中再次查看它。
收集 Cloud ID 和 API 密钥 后，您可以使用客户端连接到您的 Elastic Cloud 实例，如下所示
client = Elasticsearch::Client.new( cloud_id: '<CloudID>', api_key: '<ApiKey>' )
如果您通过开发控制台或 REST API 创建 API 密钥，则可能会获得一对 id 和 APIKey 值。客户端还接受 api_key 参数的哈希值，因此您可以传入这些值，它将在内部对 API 密钥进行编码
client = Elasticsearch::Client.new(
cloud_id: '<CloudID>',
api_key: {id: '<Id>', api_key: '<APIKey>'}
)
连接到自管集群编辑
Elasticsearch 8.0 默认提供安全性，这意味着已启用身份验证和 TLS。
要连接到 Elasticsearch 集群，您需要将 Ruby Elasticsearch 客户端配置为使用带有生成的 CA 证书的 HTTPS，以便成功发出请求。
如果您刚开始使用 Elasticsearch，我们建议您阅读有关配置和启动 Elasticsearch 的文档，以确保您的集群按预期运行。
首次启动 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 指纹，以供下一节使用。在下面的示例中，它们将分别存储在变量 ELASTIC_PASSWORD 和 CERT_FINGERPRINT 中。
根据情况，有两种方法可以验证 HTTPS 连接，可以使用 CA 证书本身进行验证，也可以通过 HTTP CA 证书指纹进行验证。
使用 CA 证书验证 HTTPS编辑
生成的根 CA 证书位于 Elasticsearch 配置位置的 certs 目录中（$ES_CONF_PATH/certs/http_ca.crt）。如果您在 Docker 中运行 Elasticsearch，则有其他文档用于检索 CA 证书。
将 http_ca.crt 文件放在可以访问的位置后，通过 ca_certs 将路径传递给客户端
client = Elasticsearch::Client.new(
host: "https://elastic:#{ELASTIC_PASSWORD}@localhost:9200",
transport_options: { ssl: { ca_path: CERT_DIR } }
)
使用证书指纹验证 HTTPS编辑
这种验证 HTTPS 连接的方法利用了之前记下的证书指纹值。获取此 SHA256 指纹值，并通过 ca_fingerprint 将其传递给 Ruby Elasticsearch 客户端
# Colons and uppercase/lowercase don't matter when using
# the 'ca_fingerprint' parameter
CERT_FINGERPRINT = '64F2593F...'
# Password for the 'elastic' user generated by Elasticsearch
ELASTIC_PASSWORD = "<password>"
client = Elasticsearch::Client.new(
host: "https://elastic:#{ELASTIC_PASSWORD}@localhost:9200",
transport_options: { ssl: { verify: false } },
ca_fingerprint: CERT_FINGERPRINT
)
每次连接将运行一次验证。
可以使用 openssl x509 和证书文件计算证书指纹
openssl x509 -fingerprint -sha256 -noout -in /path/to/http_ca.crt
如果您无法访问 Elasticsearch 生成的 CA 文件，则可以使用以下脚本通过 openssl s_client 输出 Elasticsearch 实例的根 CA 指纹
# Replace the values of 'localhost' and '9200' to the # corresponding host and port values for the cluster. openssl s_client -connect localhost:9200 -servername localhost -showcerts </dev/null 2>/dev/null \ | openssl x509 -fingerprint -sha256 -noout -in /dev/stdin
openssl x509 的输出如下所示
SHA256 Fingerprint=A5:2D:D9:35:11:E8:C6:04:5E:21:F1:66:54:B7:7C:9E:E0:F3:4A:EA:26:D9:F4:03:20:B5:31:C4:74:67:62:28
API 密钥身份验证编辑
您还可以使用 ApiKey 身份验证。
如果同时提供基本身份验证凭据和 ApiKey 配置，则 ApiKey 优先。
Elasticsearch::Client.new( host: host, transport_options: transport_options, api_key: credentials )
其中，凭据是 id 和 api_key 的 base64 编码（用冒号连接）或包含 id 和 api_key 的哈希值
Elasticsearch::Client.new(
host: host,
transport_options: transport_options,
api_key: {id: 'my_id', api_key: 'my_api_key'}
)
基本身份验证编辑
您可以在主机配置哈希中传递身份验证凭据、方案和端口
client = Elasticsearch::Client.new(
hosts:
[
{
host: 'my-protected-host',
port: '443',
user: 'USERNAME',
password: 'PASSWORD',
scheme: 'https'
}
]
)
或使用常见的 URL 格式
client = Elasticsearch::Client.new(url: 'https://username:password@localhost:9200')
要将 SSL 对等验证的自定义证书传递给基于 Faraday 的客户端，请使用 transport_options 选项
Elasticsearch::Client.new(
url: 'https://username:password@localhost:9200',
transport_options: {
ssl: { ca_file: '/path/to/http_ca.crt' }
}
)
用法编辑
以下代码段显示了使用 Ruby 客户端的示例
require 'elasticsearch'
client = Elasticsearch::Client.new log: true
client.cluster.health
client.index(index: 'my-index', id: 1, body: { title: 'Test' })
client.indices.refresh(index: 'my-index')
client.search(index: 'my-index', body: { query: { match: { title: 'test' } } })
在函数即服务环境中使用客户端编辑
本节说明了在函数即服务 (FaaS) 环境中利用 Elasticsearch 客户端的最佳实践。最有效的优化是在函数（全局范围）之外初始化客户端。这种做法不仅可以提高性能，还可以启用后台功能，例如嗅探。以下示例提供了最佳实践的框架。
GCP 云函数编辑
require 'functions_framework'
require 'elasticsearch'
client = Elasticsearch::Client.new(
cloud_id: "elasic-cloud-id",
user: "elastic",
password: "password",
log: true
)
FunctionsFramework.http "hello_world" do |request|
client.search(
index: 'stack-overflow',
body: {
query: {
match: {
title: {
query: 'phone application'
}
}
}
}
)
end
AWS Lambda编辑
require 'elasticsearch'
def client
@client ||= Elasticsearch::Client.new(
cloud_id: "elastic-cloud-id",
user: "elastic",
password: "password",
log: true
)
end
def lambda_handler(event:, context:)
client.search(
index: 'stack-overflow',
body: {
query: {
match: {
title: {
query: 'phone application'
}
}
}
}
)
end
用于评估这些建议的资源
启用兼容模式编辑
Elasticsearch 服务器版本 8.0 引入了一种新的兼容模式，可以让您从 7 平滑升级到 8。简而言之，您可以将最新的 7.x Elasticsearch 客户端与 8.x Elasticsearch 服务器一起使用，从而有更多空间来协调代码库升级到下一个主要版本。
如果要利用此功能，请确保您使用的是最新的 7.x 客户端，并将环境变量 ELASTIC_CLIENT_APIVERSIONING 设置为 true。客户端在内部处理其余部分。对于每个 8.0 及更高版本的客户端，您都准备好了！默认情况下启用兼容模式。