NEST连接配置选项

前言

尽管NEST使用了比较默认的合理的连接配置来与Elasticsearch集群进行交互，但你仍然提供了大量的配置选项和组件来改变默认的配置行为。比如，可自定义设置的有：Configuration options,Connection pools,Modifying the default connection以及Working with certificates等。

本文将和大家一起了解连接配置(Configuration options)。

连接配置(Configuration options)

使用Elasticsearch.Net和NEST连接到Elasticsearch是一件很容易的事情，但是你完全有可能想要改变默认的连接行为。在ConnectionConfiguration和ConnectionSettings中，提供了许多用于低阶客户端Elasticsearch.Net的配置选项和用于高级客户端NEST的配置选项，你可以通过这些配置选项来控制客户端如何与Elasticsearch连接和交互。

ConnectionConfiguration上的配置选项

以下是ConnectionConfiguration上可用的连接配置选项列表，由于ConnectionSettings派生看ConnectionConfiguration，因此这些选项对低阶客户端Elasticsearch.Net和高级客户端NEST都可用，这些选项分别是：

• ApiKeyAuthentication

  设置与所有发送到Elasticsearch的Api密钥(Api Key)

• BasicAuthentication

  设置与所有请求一起发送到Elasticsearch的基本身份验证凭据

• ClientCertificate

  使用X509Certificate对所有HTTP请求进行身份验证。还可以使用ClientCertificates对单个请求进行设置

• ClientCertificates

  使用配置的证书对所有HTTP请求进行身份验证。还可以使用ClientCertificates对单个请求进行设置

• ConnectionLimit

  设置可以连接到Elasticsearch服务的并发连接数。对于所有非基于System.Net.Http.CurlHandler的IConnection实现，其默认并发连接数的值为80。对于基于System.Net.Http.CurlHandler的实现，默认值为Environment.ProcessorCount。

  对于桌面CLR，当创建ServicePoint对象时，此设置应用于ServicePointManager对象上的DefaultConnectionLimit属性，影响默认的连接实现。

  对于Core CLR，此设置应用于IConnection默认实现的HttpClient中使用的HttpClientHandler实例上的MaxConnectionsPerServer属性。

• DeadTimeout

  当一个节点被标记为非存活状态时，会设置默认的非存活超时系数。一些连接池可能使用平滑的超时时间，但有一些会使用这个系数并以指数的方式递增。

• DisableAutomaticProxyDetection

  禁用自动检测代理

• DisableDirectStreaming

  确保ElasticsearchResponse<T>中的响应字节总是可用的(不会被直接转换成数据流)

• DisableMetaHeader

  默认情况下，禁用包含在所有请求中的元消息头。此消息头会携带关于客户端和运行时的一些轻量级信息。

• DisablePing

  当节点被第一次使用或者被被标记为非存活节点后的第一次使用时，NEST客户端会发送一个Ping命令以确认当前节点状态。当然，你也可以全局禁用这些默认的Ping操作。

• EnableDebugMode

  开启一些有助于调试的设置，如：DisableDirectStreaming(),PrettyJson()等，这些设置可以帮助你审查原始的请求和响应的JSON结果。它还会请求服务器返回关于错误的完整堆栈跟踪信息。

• EnableHttpCompression

  对请求和响应开启gzip压缩。

  同时需要在Elasticsearch服务器开启http压缩配置

• EnableHttpPipelining

  允许请求被管道化。

• EnableTcpKeepAlive

  设置TCP连接的keep-alive选项。

• GlobalHeaders

  设置一个全局的请求头信息的集合。当每次请求都需要携带某个/某些头信息时会很有用，例如一个自定义的auth头信息。

• GlobalQueryStringParameters

  设置一个全局的请求查询参数信息，这些参数会在每次请求时一起被发送到远程服务器，比如，设置一个全局API密钥的查询参数等 。

• IncludeServerStackTraceOnError

  强制所有请求都附带?error_trace=true的查询参数，此设置告诉Elasticsearch服务器返回 堆栈跟踪作为序列化异常的一部分，默认值为false。

• MaxDeadTimeout
  设置一个节点的最大 “非存活”超时时间。不同的IConnectionPool实现可能有不同的默认值。

• MaximumRetries

  设置给定请求的最大重试次数。

• MaxRetryTimeout

  设置运行时的请求的最大重试超时时间，当没有被设置时，默认是RequestTimeout对应的值(60秒)。

• NodePredicate

  注册一个选择哪些节点上执行API调用的谓词。注意，嗅探请求会忽略这个谓词，并且总是在所有节点上执行。当使用支持重播节点的IConnectionPool实现时，默认情况下常规API调用仅会在主节点进行。

• OnRequestCompleted

  注册一个当从Elasticsearch收到响应后被调用的Action<T>委托。当你需要实现自定义日志时会很有用。通过多次调用这个事件，可以注册多个回调。

• OnRequestDataCreated

  注册一个当RequestData被创建后调用的Action<T>委托。通过多次调用这个事件，可以注册多个回调。

• PingTimeout

  为ping请求设置默认的超时时间(以毫秒为单位)，ping请求用于确定一个节点是否存活。ping应该尽可能快地失败。

• PrettyJson

  强制在所有请求中追加?pretty=true查询参数，让Elasticsearch返回美化后的JSON字符串，默认值为false。

• Proxy

  可以用这个方法设置网络代理。

• RequestTimeout

  为每个请求设置Elasticsearch的默认超时时间(以毫秒为单位)。默认为60秒。

• ServerCertificateValidationCallback

  注册ServerCertificateValidationCallback委托，每个端点都会调用这个委托，直到返回true。

• SkipDeserializationForStatusCodes

  配置客户端跳过某些状态码的反序列化，如果你使用代理运行Elasticsearch，那么返回的401,500状态码是HTML文本格式的。

• SniffLifeSpan

  设置集群状态过期的持续时间，然后应该再次执行嗅探。IConnectionPool必须支持重播，否则将永远不会发生嗅探。默认值为1小时。如果设置为null，则嗅探功能将被禁用。嗅探只会发生在SupportsReseeding返回为true的连接池上。

• SniffOnConnectionFault

  如果连接池支持重播，则在调用失败时启用重新嗅探集群。默认值true。

• SniffOnStartup

  如果连接池支持重播，则在节点第一次被使用时连接池启用嗅探功能。

• ThrowExceptions

  当调用在客户端或Elasticsearch服务器上导致异常时，在客户端抛出一个异常(SuccessOrKnownError为false时除外)。

• TransferEncodingChunked

  是否启用分块Transfer-Encoding来发送请求，默认为false。

• UserAgent

  设置客户端代理的字符串。

ElasticLowLevelClient的连接配置

以下是一个关于ElasticLowLevelClient的连接配置示例：

var connectionConfiguration = new ConnectionConfiguration()
    .DisableAutomaticProxyDetection()
    .EnableHttpCompression()
    .DisableDirectStreaming()
    .PrettyJson()
    .RequestTimeout(TimeSpan.FromMinutes(2));

var lowLevelClient = new ElasticLowLevelClient(connectionConfiguration);

ConnectionSettings选项

以下是一些关于ConnectionSettings可用的配置选项：

• DefaultDisableIdInference

  对给定的CLR类型禁用自动Id推断。

  默认情况下，对于CLR类型的数据来说，NEST会将属性名为Id的值自动映射到Elasticsearch的_id字段。如果要禁用所有CLR的Id推断功能，请使用DefaultDisableIdInference。

• DefaultFieldNameInferrer

  指定如何从CLR属性名推断字段名。

  默认情况下，NEST使用驼峰命名规则。例如，CLR属性EmailAddress将被推断为emailAddress文档字段名。

• DefaultIndex

  当没有显式地指定索引，并且没有为请求指定的给定CLR类型指定默认索引时，会使用默认索引。

• DefaultMappingFor

  指定如何为给定的CLR类型推断映射。映射可以推断出给定CLR类型的索引、id和关系名，以及控制CLR属性的序列化行为。

ElasticClient的连接配置

以下是ElasticClient的连接配置示例：

var connectionSettings = new ConnectionSettings()
    .DefaultMappingFor<Project>(i => i
        .IndexName("my-projects")
        .IdProperty(p => p.Name)
    )
    .EnableDebugMode()
    .PrettyJson()
    .RequestTimeout(TimeSpan.FromMinutes(2));

var client = new ElasticClient(connectionSettings);

Basic Authentication身份认证可以直接通过节点的URI进行设置，如：

var uri = new Uri("http://username:password@localhost:9200");
var settings = new ConnectionConfiguration(uri);

但是，当使用连接池与多个节点连接时，这可能不是很合适，特别是当所使用的连接池能够自己重种时。出于这个原因，还是建议在ConnectionSettings上指定凭据。