Elasticsearch.Nest 教程系列 2-1 连接：Configuration options | 配置选项

  • 本系列博文是“伪”官方文档翻译（更加本土化），并非完全将官方文档进行翻译，而是在查阅、测试原始文档并转换为自己真知灼见后的“准”翻译。有不同见解 / 说明不周的地方，还请海涵、不吝拍砖 ：）

  • 官方文档见此：https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/introduction.html

  • 本系列对应的版本环境：ElasticSearch@7.3.1，NEST@7.3.1，IDE 和开发平台默认为 VS2019，.NET CORE 2.1

NEST 默认情况下使用预设的值与 ElasticSearch 集群进行交互，并提供了许多配置选项和组件来修改默认值（行为）。

你可以修改 ConnectionConfiguration 和 ConnectionStrings 的属性以达到修改默认连接行为的效果：

  • ConnectionConfiguration：面向 ElasticSearch.Net。

  • ConnectionStrings：面向 NEST。

配置 ConnectionConfiguration

因为 ConnectionStrings 继承自 ConnectionConfiguration，所以以下选项（方法/属性）适用于 ConnectionConfiguration 和 ConnectionStrings。

  • ApiKeyAuthentication： 与所有请求一起发送到Elasticsearch的 Api Key。

  • BasicAuthentication： 与所有请求一起发送到Elasticsearch的 基本身份验证凭证。

  • ClientCertificate： 为所有 HTTP 请求使用 X509Certificate 认证。你也可以在每一个请求上通过 ClientCertificates 属性来进行设置。

  • ConnectionLimit： 限制并发连接数。

    • 对于非 System.Net.Http.CurlHandler 连接，默认 80。
    • 对于 System.Net.Http.CurlHandler，取决于 CPU 数量。
    • 对于非 CORE CLR，该设置应用于创建 ServicePoint 对象时的 ServicePointManager 对象的 DefaultLConnectionLimit 属性，这会影响默认的 IConnection 实现。
    • 对于 CORE CLR，该设置应用于实现了 IConnection 接口且内部使用了 HttpClientHandler 实例的 MaxConnectionsPerServer 属性的 HttpClient 上。

  • DeadTimeout： 超时失效时间，用于设置节点被标记为失效的默认失效超时`因子`。一些连接池可能使用固定的超时时间，而另外的一些则使用此超时时间因子并以指数方式增加。

  • DisableAutomaticProxyDetection： 禁用自动检测代理。

  • DisableDirectStreaming： 确保响应字节在ElasticsearchResponse 上始终可用，默认为 false。

    • 依赖于注册的序列化器，该选项会将响应数据先缓存在内存中，存在潜在的性能影响，生产环境不建议使用（置为false）。

  • DisablePing： 是否禁用 ping。

  • EnableDebugMode： 是否启用调试模式。将该选项设置为 true 有助于调试，例如 DisableDirectStreaming() 和 PrettyJson() 以便可以检查原始请求和响应的 JSON 字符串。另外开启该选项后会向服务器获取有错误的完整堆栈信息。

  • EnableHttpCompression： 是否在请求和响应的时候启用 http gzip 压缩传输。

    • 若要启用该选项的话，需要在 ElasticSearch 服务上也启用该选项。启用方式见此。

  • EnableHttpPipelining： 是否启用 HTTP Pipeline。

    • 同样的，若要启用该选项的话，需要在 ElasticSearch 服务上也启用 http pipeline 选项。

  • EnableTcpKeepAlive： 是否启用 TCP 保持。

    • 部署在 windows 上的话，需要设置 ServicePointManager.SetTcpKeepAlive。

  • GlobalHeaders： 设置全局的请求头信息。

    • 如自定义的“认证”请求头信息。

  • GlobalQueryStringParameters： 设置全局的查询字符串信息。

    • 如若每次都要传输的 ApiKey。

  • IncludeServerStackTraceOnError： 默认 false，强制所有请求都附加“?error_trace=true”查询参数。这会导致 ES 服务发生错误时返回堆栈信息。

  • MaxDeadTimeout： 将节点标记为失效的最长时间。不同的 IConnectionPool 实现可以选择不同的默认值。

  • MaximumRetries： 请求的最大重试次数。

  • MaxRetryTimeout： 最大重试超时时间：限定总的运行时间，包括重试，与 RequestTimeout 分开，当不设置的时候，默认值为 RequestTimeout 设定的值（RequestTimeout 默认为 60s）。

  • RequestTimeout： 用于设定每个请求的超时时间，默认 60s。

    • 你可以将这个值设大一点，然后再 ES 服务端设置请求的超时时间。

  • NodePredicate： 注册一个谓词以选择在哪个节点上执行 API 调用。需要注意的时 Sniffing 相关的嗅探请求会忽略该谓词，并始终在所有节点上执行。

    • 当使用了支持 嗅探节点 的 IConnectionPool 实现的时候，默认会忽略”仅主节点“可用的常规 API 调用。
    • 当使用静态或单节点连接池时，会将你实例化的客户端节点原封不动的进行返回。

  • OnRequestCompleted： ，Action，请求完成事件，当从 ES 服务端接收到响应的时候会触发。该事件适用于记录日志。多个回调的话可以注册多次。

  • OnRequestDataCreated： Action，当请求数据创建完成的时候会被触发。多个回调的话可以注册多次。

  • PingTimeout： 设定默认的 ping 超时时间，可用来检测节点是否还存活着。

  • PrettyJson： 强制在所有的请求连接上附加”?pretty=true“请求参数，会返回格式化后的 JSON。同样的，会强制客户端发送格式化的 JSON。默认 false。

  • Proxy： 如果你的连接需要经过代理的话，可以用此选项来指定代理代理的 url。

  • ServerCertificateValidationCallback： 服务端证书验证回调事件，每一个终结点都会调用该事件直到返回 true。一旦返回了 true，则在该主机的 ServiceEndpoint 生命周期内，该终结点都是被验证过的。

  • SkipDeserializationForStatusCodes： 配置特定的状态码跳过反序列化，当你通过代理访问 ES，返回 401，500 状态码的时候，就可以跳过反序列化。

  • SniffLifeSpan： 用于设置嗅探的持续时间戳。在设置的持续时间之前，集群状态被认为是 stale（过期的，不复存在的），应再次执行嗅探。

    • IConnectionPool 必须发信号来表示它支持被重新广播，否则，嗅探将永不会被执行。
    • 默认时间是 1小时，设置为 null 可以完全禁用该功能。
    • 嗅探只会发生在对 SuppotsReseeding 返回 true 的 ConnectionPools 上。

  • SniffOnConnectionFault： 如果连接池支持嗅探，则该配置用于设置是否允许当调用失败时，重新嗅探集群。默认为 true。

  • SniffOnStartup： 如果连接池支持 reseeding，则在第一次使用连接池时进行嗅探嗅探，默认为 true。

  • ThrowExceptions： 跟 C/GO 在响应时的错误检查不同。调用请求的时候，如果在客户端或 ES 服务器上发生了异常，那么客户端在调用 IsValid 的时候会抛出一个异常（除非 SuccessOrKnownError 被设置为 false）。

    • 出现此类错误的原因可能是搜索解析器错误，索引丢失异常等等。

  • TransferEncodingChunked： 是否应该使用分块传输编码发送请求，默认为 false。

  • UserAgent： 与请求一起发送的用户代理字符串，对调试很有用，有助于弄清初始化请求 ES 服务器时的客户端和框架版本。

示例：

1
2
3
4
5
6
7
8
9
10
11
public ElasticSearchClient(ElasticSearchSettings esSettings)
{
    _esSettings = esSettings;
    var settings = new ConnectionSettings(new Uri(_esSettings.ServerUri)).DefaultIndex(_esSettings.DefaultIndex);
    settings.DeadTimeout(new TimeSpan(1,0,0));
    settings.DisableAutomaticProxyDetection();
    settings.DisableDirectStreaming();
    settings.DisablePing();
    settings.EnableHttpCompression();
    _client = new ElasticClient(settings);
}

配置 ConnectionSettings

以下为仅适用于 ConnectionSettings 的配置选项

  • DefaultDisableIdInference： 禁用给定 CLR 类型的自动 ID 推断。NEST 默认会将命名为 Id 的属性作为 ES 中的 _id 发送给 ES。

  • DefaultFieldNameInferrer： 指定如何从 CLR 属性名推断字段名称。默认情况下，NEST 使用 camel 命名方式，如在 CLR 中声明的属性名为 EmailAddress，将会被推断为 emailAddress 作为 ES 文档的字段名。

  • DefaultIndex： 默认索引名称，当没有显式指定索引名的时候，就会用默认索引名。

  • DefaultMappingFor： 指定如何映射 ES 文档字段和 CLR 的属性。映射关系可以推断给定的 index，id 和 相关 name 以及控制序列化 CLR 属性的行为。

示例：

1
2
3
4
5
6
7
8
public ElasticSearchClient(ElasticSearchSettings esSettings)
{
    _esSettings = esSettings;
    var settings = new ConnectionSettings(new Uri(_esSettings.ServerUri)).DefaultIndex(_esSettings.DefaultIndex);
    settings.DefaultMappingFor<User>(ent=>ent.IndexName("my-user").IdProperty(prop=>prop.GroupId))
        .PrettyJson()
    _client = new ElasticClient(settings);
}