聊聊es中API的不曾关注的小细节

引言

之前我们提到了es暴露了HTTP接口，通过RESTFUL风格的api来进行操作，先回顾一下RESTFUL。如下图所示：

在共识下的RESTFUL API标准下，es对RESTFUL的支持又有哪些异同和标准呢？今天，我们就来详细聊一聊es的REST API。

公约

也许如我们之前在Kibana中操作查询，创建，仿佛只需要简单的写http请求就好，并没有感知到在es对于RESTFUL的请求做了哪些公约、限制。恰如此，es推荐Kibana进行数据的操作，因为Kibana的操作会让你更专注于实现数据的业务逻辑
。

header信息

众所周知，http请求里的header信息包罗万象，从请求来源(Host,Referer)、客户端(User-Agent)、文件类型(Content-type)等等，如果你感兴趣，可以打开浏览器的开发者模式，查看相关的请求的header都代表着什么意思，或者你可以加入我们，群里有各种各样的知识分享，总有一款属于你的菜。

Content-type

es的API请求，Content-type的header是必填项
。用来约束请求体的文件格式类型，同时也告诉服务端，用什么格式来解析请求体。目前大部分的API支持的格式JSON、YAML，CBOR，SMILE，复杂查询的API支持的格式有NDJSON，JSON，SMILE，其他的格式会被服务器以错误信息返回。同时，所有的请求体编码格式只支持UTF-8
,同样,es的返回信息的编码也是UTF-8。

JSON和YAML是我们比较耳熟能详的数据结构格式，在这里我们简单举几个例子。

1.JSON的请求和返回

GET es-learn-000006/_search
{
  "query": {
    "match": {
      "name.first": "John"
    }
  }
}

1.YAML的请求和返回

---
took: 1
timed_out: false
_shards:
  total: 1
  successful: 1
  skipped: 0
  failed: 0
hits:
  total:
    value: 1
    relation: "eq"
  max_score: 1.0
  hits:
  - _index: "es-learn-000006"
    _id: "1"
    _score: 1.0
    _source:
      name:
        first: "John"
        middle: "Winston"
        last: "Lennon"

1.CBOR和SMILE

CBOR为了解决编码问题和数据安全问题，采用二进制格式进行传输，SMILE同样为了解决传输的空间问题，这两种作为我们扩展的数据结构了解即可，工作中，JSON作为我们主流的数据传输格式。同样你可以采用format参数来看看CBOR和SMILE的格式，但从Kibana里面的返回体，并没有直接的可读性。

值得提一嘴的是，当时用SMILE格式返回的时候，返回体中有一个笑脸的标识。

追溯利器X-Opaque-Id，traceparent

GET 和 POST的处理

我们知道，在RESTFUL的设计理念中，GET请求是URL中携带参数，而没有正式的请求体，在Elasticserch中，这是一个很不方便的操作，我们的参数，复杂查询，聚合等等在JSON请求体中更容易实现，因此，对于GET请求，es是允许进行携带请求体的，并且如果你觉得这个违背了你RESTFUL的强迫症，你可以将GET请求换成POST请求。

通用参数

可视化友好参数

1.?pretty=true
（仅在测试时候使用）

这个参数会让JSON在展示时候的格式更加的美观，更加的利于阅读

1.?human=true

这个参数会将一些时间，大小划分成容易读的单位，例如时间时间单位h，大小单位kb等，这个参数默认情况下是关闭的

1.?format=yaml

这个参数可以将返回值变更格式，我们在上面已经讨论过了，具体支持的一些格式。

日期表达式

时间筛选，无论是在日志数据，还是订单这种业务数据都是很常见的需求，那么es在日期的处理上，不仅仅是提供多种格式的数据，同时对于时间处理上，提供了很多人性化的操作。

例如，在范围筛选中，gt
和lt
表示晚于，早于。+1h表示加一小时，-1d表示减一天。

同时提供了now
关键字表示当前时间

返回过滤器filter_path

filter_path
指定返回的字段。

如果我们不加filter_path查询

GET es-learn-000006/_search

返回结果：

此时我们只想要hits里面的_source
和_score
,我们可以这么查询：

GET /es-learn-000006/_search?filter_path=took,hits.hits._source,hits.hits._score

返回结果：

同时，filter_path
支持正则表达式的匹配。

GET /_cluster/state

这个请求是用来查看集群的状态

返回结果：

当我们只想看索引的状态的时候，我们可以这么查询：

GET /_cluster/state?filter_path=metadata.indices.*.stat*

返回结果：

问题排错参数

?error_trace=true

当我们输入一个错误操作的时候，es会报简短的错误原因，例如：

POST /es-learn-000006/_search?size=char

当然我们可以看到，错误原因是字符串char无法转换成数字，如果我们想看报错的堆栈信息呢？

POST /es-learn-000006/_search?size=char&error_trace=true

To Be Continued

至此，我们将RESTFUL的api简单的介绍了一下，API是访问es的灵魂，在种类上，提供了各种各样特定的API，例如节点操作、索引操作、集群操作、生命周期操作等等，等等，我们后续一点一点的揭开面纱。同时，我有一个问题想跟你探讨，es同样对版本的升级的api做了兼容，你了解么？欢迎跟我们一起讨论？