elasticsearch02-通用API规范

通用API规范

在介绍下面的curd等api之前，先介绍一些通用的API规范。

多index 搜索通用参数

大多数API都支持跨index去进行查询等操作，例如使用：GET /test1,test2这种列举的方式；也可以用通配符的方式GET /test*的方式；通配符还支持排除的方式GET /test*,-test2.

当使用跨index的时候，有如下几个默认的参数：

1. ignore_unavailable. 可以选择true或false，去决定是否忽略那些不可用的index，不可用的index是指那些不存在或关闭了的。
2. allow_no_indices.可以选择true或false，去决定根据索引通配符表达式去搜索，如果no one index match，那么会根据allow_no_indices选择是否为true，确定结果。
3. expand_wildcards.可以选择open，close，none或all。open会只在指定的index中搜索，close不在指定的index中搜索，all所有index，none没有index搜索。

Note：这几个参数只适合多个index一起搜索，单index不能用。

date math 可用于index的名称匹配

date math是es提供的时间搜索方式，也可以用于匹配index的名称（使用场景可能就是查看一段时间内每天的日志），通过特定的表达式去搜索，而不是查完过滤结果，效率会高很多。使用的方式如下：

<static_name{date_math_expr{date_format|time_zone}}>

举个例子，假设当前时间是 2024 年 3 月 22 日中午 utc

<logstash-{now/M{YYYY.MM}}> 其结果就是 logstash-2024.03

名称	含义	备注
Static_name	index的名称	对应的是logstash-
Date_math_expr	时间表达式	对应的是now/M
date_format	日期的格式	默认是YYYY.MM.dd，可不写，对应的是YYYY.MM
time_zone	时区	默认的是utc，可不写

通过上门的例子应该就能很清楚的知道date math在匹配index时候的用法了，然后需要注意一点的是，符号例如< { / 等需要进行URI转义，看下表：

符号	含义
<	%3C
>	%3E
/	%2F
{	%7B
}	%7D
|	%7C
+	%2B
:	%3A
,	%2C

常用参数选项

下面列出的这些常用参数/选项可以用于所有的API。

pretty

就是格式化respone，就在后面加上pretty即可。

适合人读的结果输出

参数human=true/false。默认false。使用之后结果更方便读。例如：

"exists_time_in_millis": 3600000 or "size_in_bytes": 1024

当设置参数 human=true时，结果为：

"exists_time": "1h"` or `"size": "1kb"

Date Math

搜索两个时间内的数据，通常的做法可能time>2019&time<2020这种，es提供了更方便的Date Math（笔者理解为时间计算）的方式。Date Math以一个锚点开始，然后在这之后可以跟一个或多个特定的表达式。

锚点有两种：1. 当前时间 now ；2. 任意时间+|| 例如 2019-01-01||

特定的表达式一般一下三种，当然下面的1可以替换为别的数字；

• +1h: 增加一个小时
• -1d: 减去一个小时
• /d: 向下到最近的日期（也就是零点）

然后支持的时间格式包括常用的Y，M，h等等，看下表：

符号	含义
y	Years
M	Months
w	Weeks
d	Days
h	Hours
H	Hours
m	Minutes
s	Seconds

然后借用官方的例子，假定现在的日期是2001-01-01 12:00:00，

表达式	结果
now+1h	2001-01-01 13:00:00
now-1h	2001-01-01 11:00:00
now-1h/d	2001-01-01 00:00:00
2001.02.01\|\|+1M/d	2001-03-01 00:00:00

响应过滤

通过参数filter_path来过滤响应的参数，可以返回指定的响应结果。例如：

`GET ``/_search``?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score`

返回结果为

{
  "took" : 3,
  "hits" : {
    "hits" : [
      {
        "_id" : "0",
        "_score" : 1.6375021
      }
    ]
  }
}

然后也可以使用 *（一级都符合）**（多级都符合） -（排除某个结果）这种来过滤， 排除和非排除可以一起使用（这里不难但比较啰嗦，具体可以看官方文档）。

平面化

通过参数flat_settings设置结果是平面化(true)，还是json(false)的格式显示，默认是false。

---

其他还有一些如 时间单位、距离单位、文件大小单位 boolean值等，一般理解就可以，具体的可以看官方文档