Github: https://github.com/elastic/elasticsearch-net
官方文档: https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html
其他: Elasticsearch .net client NEST 5.x 使用总结
简介
这是用于.NET client for Elasticsearch的文档。本页为您提供客户端主要功能的快速概述。
特征
- 使用 REST API 进行一对一映射。
- 弹性搜索 API 的强类型请求和响应。
- 用于构建请求的流利 API。
- 常见任务(如文档的批量索引)的帮助程序。
- 基于系统.文本.json 的请求和响应的可插入序列化。
- 诊断、审核和 .NET 活动集成。
.NET client for Elasticsearch基于Elasticsearch构建,该库提供:
- 跨所有可用节点的连接管理和负载平衡。
- 请求重试和死连接处理。
安装 .NET 客户端
对于 SDK 样式的项目,您可以通过在终端中运行以下 .NET CLI 命令来安装.NET client for Elasticsearch:
或者Visual Studiodotnet add package Elastic.Clients.Elasticsearch --prerelease
或者,在 NuGet 包管理器 UI 中搜索 。Elastic.Clients.ElasticsearchInstall-Package Elastic.Clients.Elasticsearch -IncludePrerelease
连接到云部署
建议尽可能使用云 ID,因为您的客户端将自动配置为与弹性云(包括 HTTPS 和 HTTP 压缩)进行最佳使用。
作为安全最佳实践,建议为每个应用程序创建一个专用的 API 密钥,其权限仅限于应用程序有权进行的任何 API 调用所需的权限。
以下代码段演示了如何创建连接到云中弹性搜索部署的客户端实例。 ```csharp using Elastic.Clients.Elasticsearch; using Elastic.Transport;
var client = new ElasticsearchClient(“
> 将上面的占位符字符串值替换为为应用程序配置的云 ID 和 API 密钥,以访问部署。
<a name="pac16"></a>
## 连接到单个节点
单节点配置最适合连接到在负载均衡器或反向代理后面运行的多节点群集,该群集通过单个 URL 公开。在本地应用程序开发期间使用单个节点也可能很方便。如果 URL 表示单个弹性搜索节点,请注意,如果服务器无法访问或无响应,则不会提供复原能力。<br />默认情况下,身份验证和 TLS 等安全功能在Elasticsearch集群上处于启用状态。首次启动Elasticsearch时,系统会自动为 HTTP 层配置 TLS。将生成 CA 证书并将其存储在磁盘上,该证书用于对Elasticsearch集群的 HTTP 层的证书进行签名。<br />为了使客户端能够通过 HTTPS 与群集建立连接,客户端应用程序必须信任 CA 证书。最简单的选择是使用 CA 证书的十六进制编码 SHA-256 指纹。CA指纹会在您首次启动Elasticsearch时输出到终端。您将在 Elasticsearch 的输出中看到一个类似于下面的明显块(如果已经过了一段时间,您可能需要向上滚动)
```csharp
----------------------------------------------------------------
-> 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
...
----------------------------------------------------------------
记下用户密码和 HTTP CA 指纹,以用于后续部分。elastic
还可以使用以下命令随时从正在运行的集群中检索 CA 指纹:
docker exec -it elasticsearch /bin/bash
openssl x509 -fingerprint -sha256 -in config/certs/http_ca.crt
该命令返回安全证书,包括指纹。应为 。issuerElasticsearch security auto-configuration HTTP CA
SHA256 Fingerprint=14:0C:36:4D:47:5F:23:23:FF:30:FD:92:9D:25:C2:1B:F5:56:61:73:56:C5:5F:45:F9:B8:E7:D5:40:BB:65:59
-----BEGIN CERTIFICATE-----
MIIFWjCCA0KgAwIBAgIVALbLps1XZCcV4sizC5Dl/oKRtONcMA0GCSqGSIb3DQEB
CwUAMDwxOjA4BgNVBAMTMUVsYXN0aWNzZWFyY2ggc2VjdXJpdHkgYXV0by1jb25m
aWd1cmF0aW9uIEhUVFAgQ0EwHhcNMjIxMDAzMDQzMzQ5WhcNMjUxMDAyMDQzMzQ5
WjA8MTowOAYDVQQDEzFFbGFzdGljc2VhcmNoIHNlY3VyaXR5IGF1dG8tY29uZmln
dXJhdGlvbiBIVFRQIENBMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA
rHHZ5ixGPZqwCEdZd7ijQ09E10Xnbrn5mm49/w0Uxn/GNMMFvK9yzmaql64e/Ft9
sVqwixljfDnXmC099xePnY9P5YO4YJ6ATImqLQp0INbkCq1AT/AWjilcZ2vFi504
DoWLgiBer/JcfzIJb0wZ7i9b0e5CuSMMoYhQ8+8f62LQKEXAykyH396grG7But9A
sEJ5tpzToLIKFmtFZemRzy/3K1qmFR9bRFWdzmdu6GCW5OiLwgwj9/Y/62M2KSHS
F4/J9udyiJDRCCCC5b1NparAwzCpqopQafEM593If39Sa/8nr2eA+95xax5ZAi6D
JCviJ0HmIv2gqhLRkVxBv1xo3oP9GprMqZcHd8MnjDLVuJmu9SfLqmO+VJn5Yyuy
EiLHZPhnkZKD40FSW7QMaT0+8QWz/0YwhwvhpuMBjgBRtwmQiSA3YUnspLXKPVvr
TFkovvDdFCyVNhjAZ3BMASNZJBLsbS9dQAGyfve2+4zTGQCX9rNw9NiErtx9gR8i
bZVL7dk8Y5utbBVAA4IsSB848ewUS4sugQF5hIGYmLC05UjfzVzlk2a5djsVHMX9
0HzEaNkfoR2yU3kzfuNba0eKVFl3sbJaxPYLoHVkGhi7F3PLd9e6PhpNd1UhYe3q
srF47FjKrtuiCHk9G+Z645r5JyphP7O/Z5G7HRnzmBsCAwEAAaNTMFEwHQYDVR0O
BBYEFEhTqPk4HNYf0qk5Jr6GYJ/JjbPxMB8GA1UdIwQYMBaAFEhTqPk4HNYf0qk5
Jr6GYJ/JjbPxMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggIBAFIu
hEVN8F9JGJA+fKWJsTjKsf8HdPNf0Hr5IuJA81C0vkSCYqI9AsgXICHhE7crLS1t
30XHuNrWbJ5GBTr61srqcboJB09/K7TObF9YZTTEAZ7O1LGU4Xs4pIlwpZP4iIt3
/Ff0q20KpJyrX4eUz3HGo6IRiJKNw49crgLlFAb0XPnv69gVa8u4SePlWeLmqYc6
KrXIadCYan8EKtADeFlRg0xnKiGcui/VTm1MBO0wLta2aBdZhA7tnh+GT/5J9IxX
HJjRdf9FOzT6LMglWDB2v36Y55UNUxzhcSh0VQKzlI494UvD+40hZOnri0k/j3BO
1QIPaNxISROvbvw5u9NZlxH572OIv++/iLrFd9rUg51oJjm7Z8IvT/7FjLaY2y4I
zDDIN4rg+EmYGqFze8bJHw3SNsse3GzxnEYoqXHUZ6pmnUMOjMdm75/OspoJtLX2
SCtLOwqcH732VCzUSXMDi3ic256jvtHpnbpgk30feEdruB89FURrTlXx7xoTs++D
BeQRzi0VvBfVyfQdLb4U0MAsUAKDlmSzgQpzsLIEOmja2PvtQTGzE5oucY/StoPr
bIfiQTltPOsJjWNoLJNbhftntPnbLKsGOTisvPloMtuC+qJR1DxwGe269rTCG4G8
bYJxJRXNLbSOJLIvI7BJOSgyrIUaKQy5g7/YIGbs
-----END CERTIFICATE-----
以下代码段向您展示了如何使用 CA 指纹创建通过单个节点连接到您的 Elasticsearch 集群的客户端实例:
using Elastic.Clients.Elasticsearch;
using Elastic.Transport;
var settings = new ElasticsearchClientSettings(new Uri("https://192.168.3.40:9200"))
.CertificateFingerprint("<FINGERPRINT>")
.Authentication(new BasicAuthentication("<USERNAME>", "<PASSWORD>"));
var client = new ElasticsearchClient(settings);
:::warning
FINGERPRINT:14:0C:36:4D:47:5F:23:23:FF:30:FD:92:9D:25:C2:1B:F5:56:61:73:56:C5:5F:45:F9:B8:E7:D5:40:BB:65:59
USERNAME:longfc
PASSWORD:lfc123456
:::
前面的代码段演示了如何通过提供具有基本身份验证的用户名和密码来配置客户端以进行身份验证。如果愿意,您还可以使用身份验证,如云连接示例中所示。ApiKey
使用节点池连接到多个节点
若要提供复原能力,应为客户端尝试与之通信的群集配置多个节点。默认情况下,客户端以轮循机制方式循环遍历每个请求的节点。客户端还会跟踪不正常的节点,并避免向它们发送请求,直到它们变得正常。
此配置最适合连接到已知的小型群集,在该群集中,不需要探查即可检测群集拓扑。
以下代码段演示如何使用静态节点池连接到多个节点:
using Elastic.Clients.Elasticsearch;
using Elastic.Transport;
var nodes = new Uri[]
{
new Uri("https://myserver1:9200"),
new Uri("https://myserver2:9200"),
new Uri("https://myserver3:9200")
};
var pool = new StaticNodePool(nodes);
var settings = new ElasticsearchClientSettings(pool)
.CertificateFingerprint("<FINGERPRINT>")
.Authentication(new ApiKey("<API_KEY>"));
var client = new ElasticsearchClient(settings);
API_KEY:可登录到kibana创建API_KEY API_KEY Base64:OGxhRHJZTUJHUllwbi1lTHpycXg6WnBObGVfaVJUU21Tems3aUFsbjBEUQ==
{
"id":"8laDrYMBGRYpn-eLzrqx",
"name":".NET API_KEY",
"api_key":"ZpNle_iRTSmSzk7iAln0DQ",
"encoded":"OGxhRHJZTUJHUllwbi1lTHpycXg6WnBObGVfaVJUU21Tems3aUFsbjBEUQ=="
}
配置示例
使用客户端连接到 Elasticsearch 很容易,但您可能希望更改默认的连接行为。有许多可用的配置选项可用于控制客户端与 Elasticsearch 的交互方式。ElasticsearchClientSettings
var settings= new ElasticsearchClientSettings()
.DefaultMappingFor<Project>(i => i
.IndexName("my-projects")
.IdProperty(p => p.Name)
)
.EnableDebugMode()
.PrettyJson()
.RequestTimeout(TimeSpan.FromMinutes(2));
var client = new ElasticsearchClient(settings);