单个请求的配置

按请求配置

下面的示例会忽略 MissingDocument404Exception ，返回的是 Elasticsearch 提供的 JSON 数据。

忽略异常

Elasticsearch 类库会对普通的问题抛出异常。这些异常跟 Elasticsearch 返回的 HTTP 响应码一一对应。例如，尝试获取一个不存在的文档会抛出 MissingDocument404Exception。

抛出异常是对找不到文件、语法错误、版本冲突等问题有用且一致的方法。但有时您希望处理返回数据而不是捕获异常（通常在单元测试中有用）。

如果想忽略异常，您可以配置 ignore 参数。ignore 参数要作为 client 的参数配置在请求数组中。例如，这个示例会忽略 MissingDocument404Exception ，而返回的是 Elasticsearch 提供的 JSON 数据。

$client = ClientBuilder::create()->build();
$params = [
    'index'  => 'test_missing',
    'type'   => 'test',
    'id'     => 1,
    'client' => [ 'ignore' => 404 ] (1)
];
echo $client->get($params);
> {"_index":"test_missing","_type":"test","_id":"1","found":false}

• 这里将会忽略404异常

你可以通过数组指定忽略多个 HTTP 状态码：

$client = ClientBuilder::create()->build();
$params = [
    'index'  => 'test_missing',
    'type'   => 'test',
    'client' => [ 'ignore' => [400, 404] ] (2)
];
echo $client->get($params);
> No handler found for uri [/test_missing/test/] and method [GET]

• ignore 也会接收数组。在这个示例中, BadRequest400Exception 和 MissingDocument404Exception 都会被忽略

应该注意的是，返回数据是字符串，而不是一个 JSON 数据。在第一个示例中，返回数据是一个可以被转换的 JSON 对象。在第二个示例中，它只是一个字符串。

一旦客户端无法知道返回异常的数据格式，就不会对返回结果进行解码。

自定义查询参数

有时你需要提供自定义参数，比如为第三方插件或者连接提供认证 token。 在 Elasticsearch-php 定义着所有的查询参数，这是为了防止你指定一个参数，而这个参数是不被 Elasticsearch 接受的。

如果你需要自定义参数，你需要忽略这种白名单机制。所以，将它们以数组的形式添加到 custom 参数里面：

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'parent' => 'abc',              // 列入白名单的 Elasticsearch 参数
    'client' => [
        'custom' => [
            'customToken' => 'abc', // 用户定义的，不是白名单， 未选中
            'otherToken' => 123
        ]
    ]
];
$exists = $client->exists($params);

增加响应的冗长

默认情况下，客户端仅返回响应体信息。如果需要响应的更多信息（如 transfer，响应头，状态码等），可以通过配置 verbose 参数来让客户端启用返回冗长响应的功能。

不配置 verbose 参数的情况下的响应体：

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1
];
$response = $client->get($params);
print_r($response);
Array
(
    [_index] => test
    [_type] => test
    [_id] => 1
    [_version] => 1
    [found] => 1
    [_source] => Array
        (
            [field] => value
        )
)

配置 verbose 参数的情况下的响应体：

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'client' => [
        'verbose' => true
    ]
];
$response = $client->get($params);
print_r($response);
Array
(
    [transfer_stats] => Array
        (
            [url] => http://127.0.0.1:9200/test/test/1
            [content_type] => application/json; charset=UTF-8
            [http_code] => 200
            [header_size] => 86
            [request_size] => 51
            [filetime] => -1
            [ssl_verify_result] => 0
            [redirect_count] => 0
            [total_time] => 0.00289
            [namelookup_time] => 9.7E-5
            [connect_time] => 0.000265
            [pretransfer_time] => 0.000322
            [size_upload] => 0
            [size_download] => 96
            [speed_download] => 33217
            [speed_upload] => 0
            [download_content_length] => 96
            [upload_content_length] => -1
            [starttransfer_time] => 0.002796
            [redirect_time] => 0
            [redirect_url] =>
            [primary_ip] => 127.0.0.1
            [certinfo] => Array
                (
                )
            [primary_port] => 9200
            [local_ip] => 127.0.0.1
            [local_port] => 62971
        )
    [curl] => Array
        (
            [error] =>
            [errno] => 0
        )
    [effective_url] => http://127.0.0.1:9200/test/test/1
    [headers] => Array
        (
            [Content-Type] => Array
                (
                    [0] => application/json; charset=UTF-8
                )
            [Content-Length] => Array
                (
                    [0] => 96
                )
        )
    [status] => 200
    [reason] => OK
    [body] => Array
        (
            [_index] => test
            [_type] => test
            [_id] => 1
            [_version] => 1
            [found] => 1
            [_source] => Array
                (
                    [field] => value
                )
        )
)

Curl 超时

通过 timeout 和 connect_timeout 参数可以配置每个请求的 Curl 超时时间。这个配置控制客户端的超时时间。 connect_timeout 参数控制在连接阶段完成前的 curl 的等待时间。而 timeout 参数则控制整个请求完成前最多需要等待多长时间。

如果超过请求时间, curl 将会关闭链接并返回一个错误. 两个参数都要用秒作为单位指定.

备注：客户端超时不意味着 Elasticsearch 会中止请求. Elasticsearch 将会继续执行请求直到请求完成。在慢查询或批量查询的情况下，操作会继续在后台执行，对于客户端来这些动作说是隐蔽的。 如果你的客户端在超时后立即终止了连接，然后又发出了另一个请求，由于客户端没有服务器端的"背压"机制，会导致服务端过载。遇到这种情况，你会发现连接池队列会逐渐增大，当超出队列的负荷时，Elasticsearch 会发送 EsRejectedExecutionException 异常。

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'client' => [
        'timeout' => 10,        // 10秒钟超时
        'connect_timeout' => 10
    ]
];
$response = $client->get($params);

启用 Future 模式

客户端支持请求的异步批量处理。可以通过在客户端的选项配置中设置 future 参数为单个请求启用 Future 模式（如果 HTTP 处理器支持的情况下），使用方式如下:

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'client' => [
        'future' => 'lazy'
    ]
];
$future = $client->get($params);
$results = $future->wait();       // 处理 future

Future 模式支持两种可选值： true 或 'lazy'. 关于如何异步执行和如何进行结构的后续处理相关内容的更多细节信息请查阅 [_future_mode].

SSL 加密

通常，你需要在创建客户端时指定 SSL 配置（有关详细信息，请参阅 [安全性]），因为加密通常适用于所有请求。 但是，如果你需要该功能，也可以按请求进行配置。 例如，如果你需要在特定请求上使用自签名证书，则可以通过客户端选项中的 verify 参数指定它：

$client = ClientBuilder::create()->build();
$params = [
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'client' => [
        'verify' => 'path/to/cacert.pem'      // 使用自签名证书
    ]
];
$result = $client->get($params);