连接
本页包含将客户端连接到 Elasticsearch 所需的信息。
Elastic Cloud 是开始使用 Elasticsearch 的最简单方法。使用 Python Elasticsearch 客户端连接到 Elastic Cloud 时,您应始终使用 cloud_id
参数进行连接。创建集群后,您可以在“管理部署”页面中找到此值(如果您在 Kibana 中,请查看左上角)。
我们建议尽可能使用 Cloud ID,因为您的客户端将自动配置为与 Elastic Cloud 最佳配合使用,包括 HTTPS 和 HTTP 压缩。
from elasticsearch import Elasticsearch
# Password for the 'elastic' user generated by Elasticsearch
ELASTIC_PASSWORD = "<password>"
# Found in the 'Manage Deployment' page
CLOUD_ID = "deployment-name:dXMtZWFzdDQuZ2Nw..."
# Create the client instance
client = Elasticsearch(
cloud_id=CLOUD_ID,
basic_auth=("elastic", ELASTIC_PASSWORD)
)
# Successful response!
client.info()
# {'name': 'instance-0000000000', 'cluster_name': ...}
默认情况下,Elasticsearch 启动时会启用身份验证和 TLS 等安全功能。要连接到 Elasticsearch 集群,您需要配置 Python Elasticsearch 客户端以使用 HTTPS 和生成的 CA 证书,才能成功发出请求。
如果您刚开始使用 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_certs
选项是 Python Elasticsearch 客户端验证 HTTPS 连接的默认方式。
生成的根 CA 证书可以在 Elasticsearch 配置位置的 certs
目录中找到($ES_CONF_PATH/certs/http_ca.crt
)。如果您在 Docker 中运行 Elasticsearch,有额外的文档说明如何检索 CA 证书。
一旦您将 http_ca.crt
文件放在可访问的位置,即可通过 ca_certs
将路径传递给客户端。
from elasticsearch import Elasticsearch
# Password for the 'elastic' user generated by Elasticsearch
ELASTIC_PASSWORD = "<password>"
# Create the client instance
client = Elasticsearch(
"https://localhost:9200",
ca_certs="/path/to/http_ca.crt",
basic_auth=("elastic", ELASTIC_PASSWORD)
)
# Successful response!
client.info()
# {'name': 'instance-0000000000', 'cluster_name': ...}
如果您未指定 ca_certs
或 ssl_assert_fingerprint
,则默认情况下(如果可用)将使用 certifi 包作为 ca_certs
。
使用此方法要求使用 Python 3.10 或更高版本,并且在使用 aiohttp
HTTP 客户端库时不可用,因此不能与 AsyncElasticsearch
一起使用。
这种验证 HTTPS 连接的方法利用了之前记下的证书指纹值。获取此 SHA256 指纹值并通过 ssl_assert_fingerprint
将其传递给 Python Elasticsearch 客户端。
from elasticsearch import Elasticsearch
# Fingerprint either from Elasticsearch startup or above script.
# Colons and uppercase/lowercase don't matter when using
# the 'ssl_assert_fingerprint' parameter
CERT_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"
# Password for the 'elastic' user generated by Elasticsearch
ELASTIC_PASSWORD = "<password>"
client = Elasticsearch(
"https://localhost:9200",
ssl_assert_fingerprint=CERT_FINGERPRINT,
basic_auth=("elastic", ELASTIC_PASSWORD)
)
# Successful response!
client.info()
# {'name': 'instance-0000000000', 'cluster_name': ...}
可以使用带有证书文件的 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
不建议在未启用安全功能的情况下运行 Elasticsearch。
如果您的集群配置为明确禁用安全,则可以通过 HTTP 连接。
from elasticsearch import Elasticsearch
# Create the client instance
client = Elasticsearch("http://localhost:9200")
# Successful response!
client.info()
# {'name': 'instance-0000000000', 'cluster_name': ...}
Python Elasticsearch 客户端支持向集群中的多个节点发送 API 请求。这意味着工作负载将在集群中更均匀地分布,而不是反复向同一节点发送请求。要使用多个节点配置客户端,您可以传递一个 URL 列表,每个 URL 将用作池中的一个独立节点。
from elasticsearch import Elasticsearch
# List of nodes to connect use with different hosts and ports.
NODES = [
"https://localhost:9200",
"https://localhost:9201",
"https://localhost:9202",
]
# Password for the 'elastic' user generated by Elasticsearch
ELASTIC_PASSWORD = "<password>"
client = Elasticsearch(
NODES,
ca_certs="/path/to/http_ca.crt",
basic_auth=("elastic", ELASTIC_PASSWORD)
)
默认情况下,节点是使用轮询(round-robin)方式选择的,但可以使用 node_selector_class
参数配置备用的节点选择策略。
如果您的 Elasticsearch 集群位于负载均衡器之后(例如使用 Elastic Cloud 时),则无需配置多个节点。此时应使用负载均衡器的主机和端口。
本节包含代码片段,向您展示如何连接到各种 Elasticsearch 提供程序。所有身份验证方法都支持通过客户端构造函数或通过每个请求的 .options()
方法配置。
from elasticsearch import Elasticsearch
# Authenticate from the constructor
client = Elasticsearch(
"https://localhost:9200",
ca_certs="/path/to/http_ca.crt",
basic_auth=("username", "password")
)
# Authenticate via the .options() method:
client.options(
basic_auth=("username", "password")
).indices.get(index="*")
# You can persist the authenticated client to use
# later or use for multiple API calls:
auth_client = client.options(api_key="api_key")
for i in range(10):
auth_client.index(
index="example-index",
document={"field": i}
)
HTTP Basic 身份验证使用 basic_auth
参数,通过传递包含用户名和密码的元组。
from elasticsearch import Elasticsearch
# Adds the HTTP header 'Authorization: Basic <base64 username:password>'
client = Elasticsearch(
"https://localhost:9200",
ca_certs="/path/to/http_ca.crt",
basic_auth=("username", "password")
)
HTTP Bearer 身份验证使用 bearer_auth
参数,通过传递字符串形式的令牌。此身份验证方法适用于 服务账户令牌 和 Bearer 令牌。
from elasticsearch import Elasticsearch
# Adds the HTTP header 'Authorization: Bearer token-value'
client = Elasticsearch(
"https://localhost:9200",
bearer_auth="token-value"
)
您可以将客户端配置为使用 Elasticsearch 的 API 密钥连接到您的集群。这些密钥可以通过 Elasticsearch Create API key API 或 Kibana Stack Management 生成。
from elasticsearch import Elasticsearch
# Adds the HTTP header 'Authorization: ApiKey <base64 api_key.id:api_key.api_key>'
client = Elasticsearch(
"https://localhost:9200",
ca_certs="/path/to/http_ca.crt",
api_key="api_key",
)
Elasticsearch 服务器版本 8.0 引入了一种新的兼容模式,可让您从 7 平滑升级到 8。简而言之,您可以使用最新的 7.x Python Elasticsearch 客户端与 8.x Elasticsearch 服务器配合使用,为将您的代码库升级到下一个主要版本提供更多空间来协调。
如果您想利用此功能,请确保您使用的是最新的 7.x Python Elasticsearch 客户端,并将环境变量 ELASTIC_CLIENT_APIVERSIONING
设置为 true
。客户端会在内部处理其余部分。对于所有 8.0 及更高版本的 Python Elasticsearch 客户端,一切都已设置妥当!兼容模式默认处于启用状态。
本节介绍了在函数即服务(Function-as-a-Service,FaaS)环境中使用 Elasticsearch 客户端的最佳实践。
最重要的优化是在函数外部(即全局范围)初始化客户端。
这种做法不仅能提高性能,还能启用后台功能,例如嗅探。以下示例提供了最佳实践的框架。
异步客户端不应在函数即服务中使用,因为每次调用都必须启动新的事件循环。建议改用同步的 Elasticsearch
客户端。
from elasticsearch import Elasticsearch
# Client initialization
client = Elasticsearch(
cloud_id="deployment-name:ABCD...",
api_key=...
)
def main(request):
# Use the client
client.search(index=..., query={"match_all": {}})
from elasticsearch import Elasticsearch
# Client initialization
client = Elasticsearch(
cloud_id="deployment-name:ABCD...",
api_key=...
)
def main(event, context):
# Use the client
client.search(index=..., query={"match_all": {}})
import azure.functions as func
from elasticsearch import Elasticsearch
# Client initialization
client = Elasticsearch(
cloud_id="deployment-name:ABCD...",
api_key=...
)
def main(request: func.HttpRequest) -> func.HttpResponse:
# Use the client
client.search(index=..., query={"match_all": {}})
用于评估这些建议的资源