ES_之_API规范
前言
Github:https://github.com/HealerJean
1、多索引
大多数API都支持跨多个索引执行,可以使用简单的
test1
、test
2、test3
表示法(或对所有索引执行,用_all)
。它还支持通配 符,例如test
或test
或te*t
或*test*
,以及 “排除” ( - ) 功能,例 如-test3
。
所有多索引API都支持以下URL查询字符串参数:
key | 说明 |
---|---|
ignore_unavailable |
控制是否忽略不可用索引,包括不存在的索引或已关闭的索引。 可以设置为 true 或 false 。 |
allow_no_indices |
当通配符索引表达式结果为空时,allow_no_indices 控制请求是 否失败。可以指定 true 或 false 。例如,指定了通配符表达式 foo * 却没 有以 foo 开头的索引可用,如果此设置为 true ,请求将失败。当未指定 _all 、* 或无索引时,此设置也适用。此设置也适用于别名,以防别名 指向关闭的索引。 |
expand_wildcards |
控制通配符索引表达式可以扩展到哪种具体索引。如果指定了 open ,则通配符表达式将扩展为仅打开索引。如果指定了closed ,则通配符表达式仅扩展为 closed 索引。也可以指定这两个值( open , closed )以扩展到所有索引。 |
2、日期数学格式
索引名称支持日期解析,这样能够搜索一个时间范围内或某几段 时间内的索引,而不是搜索所有索引再筛选结果或维护别名。限制搜 索的索引数量可以减少集群上的负载并提高执行性能。例如,如果在 日常日志中搜索错误信息,可以使用日期格式名称模板将搜索严格限 制在过去两天内。
几乎所有具有 index
v参数的 API
都支持 index
参数值中包含日期数 学格式。日期数学索引名称具有以下形式:
<static_name{date_math_expr{date_format|time_zone}}>
key | 说明 |
---|---|
static_name |
是索引名称的静态文本部分。 |
date_math_expr |
是动态日期数学表达式,用于动态计算日期 |
date_format |
用来设置日期的可选格式。默认为 yyyy.MM.dd 格 式 , 且 应 该 与 Java 时 间 兼 容 |
time_zone |
用来设置时区。默认为 UTC |
2.1、日期数学字符百分比编码
字符 | URL编码 |
---|---|
< | %3C |
> | %3E |
/ | %2F |
{ | %7B |
} | %7D |
| | %7C |
+ | %2B |
: | %3A |
, | %2C |
2.2、日期数学格式解析实例
Expression |
Resolves to |
---|---|
<logstash-{now/d}> | logstash-2024.03.22 |
<logstash-{now/M}> | logstash-2024.03.01 |
<logstash-{now/M{yyyy.MM}}> | logstash-2024.03 |
<logstash-{now/M-1M{yyyy.MM}}> | logstash-2024.02 |
<logstash-{now/d{yyyy.MM.dd|+12:00}}> | logstash-2024.03.23 |
3、通用选项
3.1、格式化搜索结果
当任何请求
URL
加pretty
=true
参数时,返回的JSON
都将是格式 化的(仅用于调试)。另一个选项是设置format
=yaml
,结果以更可读的yaml
格式返回。
3.2、可读输出
统计数据以 适 合 人 ( 例 如 “
exists_time
” : “1h
” 或 “size
”:“1KB
”) 和计算机(例如“exists_time_in_millis
”:3600000
或“size_in_bytes
”:1024
)的格式返回。可以通过添加human = false
来关闭对人友好可读输出格式。当统计结果被监控工具 使用,而不是用于人阅读时,这是有意义的。此标志的默认值为false
。
3.3、格式化日期值
大多数参数都可以接受格式化日期值,例如范围查询中的
gt
和lt
,或范围内聚合中的from
和to
。表达式以基准日期开始,可以是
now
,也可以是以‖
结束的日期 字符串。基准日期后面可以有一个或多个日期数学表达式
3.3.1、时间单位
3.3.2、时间单位解析实例
3.4、返回信息过滤
所有
REST
API
都接受一个filter_path
参数,该参数可用于减少Elasticsearch
返回的响应信息。此参数采用逗号分隔的列表形式, 如下示例:
3.4.1、filter_path
过滤
GET/bank/_search?q=*&sort=account_number:asc&pretty&&filter_path=took,hits.hits._id,hits.hits._score
3.4.2、* 通配符
GET/_cluster/state?filter_path=metadata.indices.*.stat*
3.4.3、字符-前缀来排除一个或多个字段
GET/_count?filter_path=-_shards
3.5、展开设置
flat_settings
标志会影响设置信息列表 (_settings
) 的呈现。如果flat_settings
标志为true
,则以平铺格式返回设置默认值,
flat_settings
=false
⬤ 当 flat_settings
标志是以 true
平面格式返回设置时:
GET bank/_settings?flat_settings=true
{
"twitter" : {
"settings": {
"index.number_of_replicas": "1",
"index.number_of_shards": "1",
"index.creation_date": "1474389951325",
"index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
"index.version.created": ...,
"index.provided_name" : "twitter"
}
}
}
⬤ 当 flat_settings
标志是以 fales
平面格式返回设置时:
GET bank/_settings?flat_settings=false
{
"twitter" : {
"settings" : {
"index" : {
"number_of_replicas": "1",
"number_of_shards": "1",
"creation_date": "1474389951325",
"uuid": "n6gzFZTgS664GUfx0Xrpjw",
"version": {
"created": ...
},
"provided_name" : "twitter"
}
}
}
}
3.6、布尔值
所有
REST API
参数(请求参数和JSON
主体)都支持布尔值false
和true
,所有其他值都将引发错误。
3.7、数字值
所有
REST
API
都支持以字符串的形式提供数字参数。
3.8、时间单位
每当需要指定时间区间,例如对于超时参数时,时间区间必须指定单位,如表示
2
天的2d
。支持的单位如表3-5所示
3.9、数据单位
每当需要指定数据的字节大小,例如设置缓冲区大小参数时,该值必须指定单位,如
10KB
表示10
千字节。请注意,这些单元使用1024
的幂,所以1KB
表示1024
字节。支持的单位如表3-6
所示
3.10、缩略处理
无单位意味着它们没有“单位”,如“
bytes
” “Hertz
” “mete
” 或 “long tonne
”。如果这些数量中有一个很大,会把它特殊地缩略处理,
10000000
打印成10m
,7000
打印成7k
。但当我们说87
的时候,我 们还是会打印87
。支持的乘数如表3-7所示
3.11、距离单位
需要指定距离(如地理距离查询中的距离参数)时,如果未指定,则默认单位为
m
。距离可以用其他单位指定,例如1km
或2mi
(2英里)。
3.12、模糊性
一些查询和
API
支持使用模糊参数 (fuzziness
) 进行不精确的模 糊匹配。在查询
text
或keyword
字段时,fuzziness
被解释为编辑距离,也就是一个字符串需要更改的字符数,以使其与另一个字符串相同。
fuzziness
参数可以指定为如下两种值。
⬤ 0
,1
,2
:允许的最大编辑距离(或编辑次数)
⬤ AUTO
: 根据 Term
的长度生成编辑距离。可以选择自动提供低距离和高距离参数: AUTO
: [ low
] , [ high
]。如果未指定,默认值为 3
和 6
,相当于AUTO
: 3
, 6
,表示长度如,0
. . 2
必须精确匹配。 · 3
. . 5
编辑距离1。 · > 5
编辑距离 2
。 · AUTO
一般应为 fuzziness
的首选值
2.13、启用堆栈跟踪
默认情况下,当请求返回错误时,
Elasticsearch
不包括错误的 堆栈跟踪。可以通过将error_trace
参数设置为true
来启用堆栈 跟踪。
① 例如,默认情况下,将无效的 size
参数发送到 _search API
时
入参:
POST/bank/_search?size=surprise_me
出参:
{
"error" : {
"root_cause" : [
{
"type" : "illegal_argument_exception",
"reason" : "Failed to parse int parameter [size] with value [surprise_me]"
}
],
"type" : "illegal_argument_exception",
"reason" : "Failed to parse int parameter [size] with value [surprise_me]",
"caused_by" : {
"type" : "number_format_exception",
"reason" : "For input string: "surprise_me""
}
},
"status" : 400
}
② 如果设置了error_trace
= true
入参:
POST/bank/_search?size=surprise_me&error_trace=true
出参:
{
"error": {
"root_cause": [
{
"type": "illegal_argument_exception",
"reason": "Failed to parse int parameter [size] with value [surprise_me]",
"stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
}
],
"type": "illegal_argument_exception",
"reason": "Failed to parse int parameter [size] with value [surprise_me]",
"stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]n at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
"caused_by": {
"type": "number_format_exception",
"reason": "For input string: "surprise_me"",
"stack_trace": "java.lang.NumberFormatException: For input string: "surprise_me"n at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
}
},
"status": 400
}
2.14、查询字符串中的请求正文
对于不接受非
POST
请求的请求主体的库,可以将请求主体作为source
查询字符串参数传递。使用此方法时,还应使用指示源格式的 媒 体 类 型 值 ( 如application/json
) 传 递source_content_type
参 数。
2.15、Content-Type
要求
在请求正文中发送的内容的类型必须使用
Content-Type
头指 定。此头的值必须映射到API
支持的格式之一。大多数API支持JSON
、Yaml
、Cbor
等常用格式。批量和多搜索API
支持Ndjson
、JSON
和smile
,其他类型将导致错误此外,使用
source
参数时,必须使用source_content_type
参数 指定内容类型。
4、基于 URL
的访问控制
许多用户使用具有基于
URL
的访问控制的代理来安全地访问Elasticsearch
索引。对于multi-search
、multi
-get
和bulk
请求,用户可以选择在URL
以及请求主体中的每个请求上指定索引。这会使基 于URL
的访问控制变得具有挑战性。要防止用户覆盖
URL
中指定的索引,请将此设置添加到elasticsearch.yml
文件中:默认值为
true
,但当设置为false
时,Elasticsearch
将拒绝请求 主体中指定了显式索引的请求。