按请求配置

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

忽略异常

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

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

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

  1. $client = ClientBuilder::create()->build();
  2. $params = [
  3. 'index' => 'test_missing',
  4. 'type' => 'test',
  5. 'id' => 1,
  6. 'client' => [ 'ignore' => 404 ]
  7. ];
  8. echo $client->get($params);
  9. > {"_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);
  7. > No handler found for uri [/test_missing/test/] and method [GET]

ignore 参数也接收数组。在这个示例中, BadRequest400ExceptionMissingDocument404Exception 都会被忽略。

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

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

自定义查询参数

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

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

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

返回详细输出

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

没有返回详细信息,你看到的返回是这样的:

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

如果加上参数:

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

Curl 超时设置

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

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

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

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

开启 Future 模式

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

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

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

SSL 加密

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

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