按请求配置

除了配置连接层和客户端层，还可以基于每次请求来进行相关设置。具体来说是在请求体中指定相关参数数组。

忽略异常

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

异常对于处理一些问题（如找不到文档、语法错误、版本冲突等）十分有用。但是有时候你只是想要处理返回的数据而不想捕获异常。

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

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index'  => 'test_missing',
  5.     'type'   => 'test',
  6.     'id'     => 1,
  7.     'client' => [ 'ignore' => 404 ] 
  8. ];
  9. echo $client->get($params);
  11. > {"_index":"test_missing","_type":"test","_id":"1","found":false}

这里会忽略 404 异常

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

  1. $params = [
  2.     'index'  => 'test_missing',
  3.     'type'   => 'test',
  4.     'client' => [ 'ignore' => [400, 404] ] 
  5. ];
  6. echo $client->get($params);
  8. > No handler found for uri [/test_missing/test/] and method [GET]

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

注意，返回的数据是字符串格式，而不是 JSON 数据。而在第一个示例中返回的是 JSON 数据，客户端会 decode 该 JSON 数据为数组。

一旦客户端无法得知返回的异常数据格式，客户端就不会 decode 返回结果。

自定义查询参数

有时候你要自己提供自定义参数，比如为第三方插件或代理提供认证 token。在 Elasticsearch-php 的白名单中存储着所有的查询参数，这是为了防止你指定一个参数，而 Elasticsearch 却不接收。

如果你要自定义参数，你就要忽略掉这种白名单机制。为了达到这种效果，请增加 custom 参数：

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1,
  7.     'parent' => 'abc',              // white-listed Elasticsearch parameter
  8.     'client' => [
  9.         'custom' => [
  10.             'customToken' => 'abc', // user-defined, not white listed, not checked
  11.             'otherToken' => 123
  12.         ]
  13.     ]
  14. ];
  15. $exists = $client->exists($params);

返回详细输出

客户端默认只返回响应体数据。如果你需要更多信息（如头信息、相应状态码等），你可以让客户端返回更多详细信息。通过 verbose 参数可以开启这个功能。

没有返回详细信息，你看到的返回是这样的：

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1
  7. ];
  8. $response = $client->get($params);
  9. print_r($response);
  12. Array
  13. (
  14.     [_index] => test
  15.     [_type] => test
  16.     [_id] => 1
  17.     [_version] => 1
  18.     [found] => 1
  19.     [_source] => Array
  20.         (
  21.             [field] => value
  22.         )
  24. )

如果加上参数：

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1,
  7.     'client' => [
  8.         'verbose' => true
  9.     ]
  10. ];
  11. $response = $client->get($params);
  12. print_r($response);
  15. Array
  16. (
  17.     [transfer_stats] => Array
  18.         (
  19.             [url] => http://127.0.0.1:9200/test/test/1
  20.             [content_type] => application/json; charset=UTF-8
  21.             [http_code] => 200
  22.             [header_size] => 86
  23.             [request_size] => 51
  24.             [filetime] => -1
  25.             [ssl_verify_result] => 0
  26.             [redirect_count] => 0
  27.             [total_time] => 0.00289
  28.             [namelookup_time] => 9.7E-5
  29.             [connect_time] => 0.000265
  30.             [pretransfer_time] => 0.000322
  31.             [size_upload] => 0
  32.             [size_download] => 96
  33.             [speed_download] => 33217
  34.             [speed_upload] => 0
  35.             [download_content_length] => 96
  36.             [upload_content_length] => -1
  37.             [starttransfer_time] => 0.002796
  38.             [redirect_time] => 0
  39.             [redirect_url] =>
  40.             [primary_ip] => 127.0.0.1
  41.             [certinfo] => Array
  42.                 (
  43.                 )
  45.             [primary_port] => 9200
  46.             [local_ip] => 127.0.0.1
  47.             [local_port] => 62971
  48.         )
  50.     [curl] => Array
  51.         (
  52.             [error] =>
  53.             [errno] => 0
  54.         )
  56.     [effective_url] => http://127.0.0.1:9200/test/test/1
  57.     [headers] => Array
  58.         (
  59.             [Content-Type] => Array
  60.                 (
  61.                     [0] => application/json; charset=UTF-8
  62.                 )
  64.             [Content-Length] => Array
  65.                 (
  66.                     [0] => 96
  67.                 )
  69.         )
  71.     [status] => 200
  72.     [reason] => OK
  73.     [body] => Array
  74.         (
  75.             [_index] => test
  76.             [_type] => test
  77.             [_id] => 1
  78.             [_version] => 1
  79.             [found] => 1
  80.             [_source] => Array
  81.                 (
  82.                     [field] => value
  83.                 )
  84.         )
  85. )

Curl 超时设置

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

如果超过超时时间，curl 会关闭连接并返回一个致命错误。两个参数都要用 秒 作为参数。

注意：客户端超时并 不 意味着 Elasticsearch 中止请求。Elasticsearch 会继续执行请求直到请求完成。在慢查询或是 bulk 请求下，操作会在后台继续执行，对客户端来说这些动作是隐蔽的。如果客户端在超时后立即断开连接，然后又立刻发送另外一个请求。由于客户端没有处理服务端回压（译者注：这里国内翻译成背压，但是#8203;知乎有文章指出这个翻译不够精准，会造成程序员难以理解，所以这里翻译成回压）的机制，这有可能会造成服务端过载。遇到这种情况，你会发现线程池队列会慢慢变大，当队列超出负荷，Elasticsearch 会发送 EsRejectedExecutionException 的异常。

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1,
  7.     'client' => [
  8.         'timeout' => 10,        // ten second timeout
  9.         'connect_timeout' => 10
  10.     ]
  11. ];
  12. $response = $client->get($params);

开启 Future 模式

客户端支持异步方式批量发送请求。通过 client 选项的 future 参数可以开启（HTTP handler 要支持异步模式）：

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1,
  7.     'client' => [
  8.         'future' => 'lazy'
  9.     ]
  10. ];
  11. $future = $client->get($params);
  12. $results = $future->wait();       // resolve the future

Future 模式有两个参数可选： true 或 lazy 。关于异步执行方法以及如何处理返回结果的详情，请到 Future 模式 中查看。

SSL 加密

在创建客户端时，一般需要指定 SSL 配置，因为通常所有的请求都需要加密（查询 安全 一节获取更多详情）。然而，在每个请求中配置 SSL 加密也是有可能的。例如，如果你需要在某个特定的请求中使用自签名证书，你可以通过在 client 选项中配置 verify 参数：

  1. $client = ClientBuilder::create()->build();
  3. $params = [
  4.     'index' => 'test',
  5.     'type' => 'test',
  6.     'id' => 1,
  7.     'client' => [
  8.         'verify' => 'path/to/cacert.pem'      //Use a self-signed certificate
  9.     ]
  10. ];
  11. $result = $client->get($params);