elasticsearch6.7 04.API规范
Posted wtc1994
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了elasticsearch6.7 04.API规范相关的知识，希望对你有一定的参考价值。
目录
- API Conventions
- 多索引
- 索引名称支持日期格式的数学运算
- 常规选项
- 格式化相应（Pretty Result）
- 人类可读式输出（Human readable output）
- 日期数学（Date Math）
- 响应过滤（Response Filtering）
- 平面设置（Flat Settings）
- 参数（Parameters）
- 布尔值（Boolean Values）
- 数值（Number Values）
- 时间单位（Time units）
- 字节大小单位（Byte size units）
- 无单位量化（Unit-less quantities）
- 距离单位（Distance Units）
- 模糊性（Fuzziness）
- 启用堆栈轨迹（Enabling stack traces）
- 查询字符串中的请求正文（Request body in query string）
- 必要的Content-Type
- 基于URL的访问控制（Content-Type Requirements）
API Conventions
elasticsearch的REST的API是使用HTTP的JSON格式暴露的。
除非另有说明，本章中列出的约定可以在整个REST API中应用。
多索引
大多数引用index参数的API 支持跨多个索引执行，使用简单的test1,test2,test3符号（或_all用于所有的索引 ）。
它还支持通配符，例如：test*或 *test 或 te*t或*test*，以及“排除”（-）的能力，例如：test*，-test3。
所有多索引API都支持在url中使用以下查询字符串参数：
ignore_unavailable
? 控制是否忽略任何指定的索引是否不可用，包括不存在的索引或闭合索引。可以指定true或false。
allow_no_indices
? 如果通配符索引表达式导致没有具体索引，则控制是否失败。可以指定true或false。例如，如果指定了通配符表达式 foo 并且没有以 foo 开头的索引，则根据此设置，请求将失败。当指定了 _all，或 no index 时，此设置也适用。如果别名指向封闭索引，则此设置也适用于别名。
expand_wildcards
? 控制通配符索引表达式可以扩展到的具体索引类型。如果指定了open，则通配符表达式将扩展为仅打开索引。如果指定closed，则通配符表达式仅扩展为闭合索引。此外，可以指定两个值（open，closed）以扩展到所有索引。
? 如果none被指定，那么通配符扩展将被禁用，如果all 被指定，通配符表达式将扩展到所有的索引（这相当于指定open,closed）。
上述参数的默认设置取决于正在使用的api。
单个索引API（如Document API 和单索引alias API）不支持多个索引。
索引名称支持日期格式的数学运算
日期数学索引名称解析使您能够搜索一系列时间序列索引，而不是搜索所有时间序列索引，并过滤结果或保留别名。限制搜索索引的数量可以减少集群的负载，并提高执行性能。例如，如果要在日常日志中搜索错误，则可以使用日期数学名称模板将搜索限制在过去两天。
几乎所有具有index参数的API都支持index参数值中的数学运算。
日期数学索引名称采用以下形式：
<static_name {date_math_expr {DATE_FORMAT |的time_zone}}>说明:
| 参数 | 说明 |
|---|---|
| static_name | 是名称的静态文本部分 |
| date_math_expr | 是动态计算日期的动态日期数学表达式 |
| date_format | 是应该呈现计算日期的可选格式。默认为yyyy.MM.dd.格式应与java-time兼容 |
| time_zone | 是可选的时区。默认为utc |
日期数学表达式与区域设置无关。因此，除了公历之外，不可能使用任何其他日历。
您必须将日期数学索引名称表达式括在尖括号内，并且所有特殊字符都应该是URI编码的。例如：
# GET /<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
"query" : {
"match": {
"test": "data"
}
}
}日期数学字符的百分比编码,用于日期舍入的特殊字符必须如下进行URI编码：
| 符号 | URI编码 |
|---|---|
| < | %3C |
| > | %3E |
| / | %2F |
| { | %7B |
| } | %7D |
| | | %7C |
| + | %2B |
| : | %3A |
| , | %2C |
以下示例显示了不同形式的日期数学索引名称以及在当前时间为2024年3月22日中午utc时解析的最终索引名称。
| 表达式 | 解析为 |
|---|---|
| <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 |
要使用字符{ 和 } 索引名称模板的静态部分，请使用反斜杠进行转义，例如：
<elastic{ON}-{now/M}> 解析为 elastic{ON}-2024.03.01以下示例显示了一个搜索请求，它在过去三天中搜索Logstash索引，假设索引使用默认的Logstash索引名称格式 logstash-YYYY.MM.dd。
# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
"query" : {
"match": {
"test": "data"
}
}
}常规选项
以下选项可以应用于所有REST API。
格式化相应（Pretty Result）
在任何请求后追加?pretty=true，返回的JSON格式都会非常好（仅用于调试！）。另一个选项是追加
?format=yaml，有时这将导致结果以更可读的yaml格式返回。
人类可读式输出（Human readable output）
统计数据以适合人类（例如"exists_time": “1h"或"size”: “1kb”）和计算机（例如"exists_time_in_millis": 3600000或"size_in_bytes": 1024）的格式返回。可以通过添加“?human=false“查询字符串来关闭可读取的值。当统计结果被监测工具消耗时，这是有意义的，而不是用于人类消耗。human标志的默认值是 false。
日期数学（Date Math）
它接受一个格式化的日期值参数—比如在范围(range)查询的gt和lt，或在daterange aggregations中的from与to。
表达式以锚点日期开始，可以是now，也可以是以||结尾的日期字符串。这个锚定日期可以选择跟随一个或多个数学表达式：
- +1h - 加一小时
- -1d - 减去一天
- /d - 向下舍入为最近的一天
支持的时间单位与持续时间单位支持的时间单位不同。支持的单位如下：
| 单位 | 含义 |
|---|---|
| y | 年 |
| M | 月 |
| w | 周 |
| d | 天 |
| h | 小时 |
| H | 小时 |
| m | 分钟 |
| s | 秒 |
假设now是2001-01-01 12:00:00，一些例子是：
now+1h
? now以毫秒格式加一个小时。解析后为：2001-01-01 13:00:00
now-1h
? now以毫秒格式加一个小时。解析后为：2001-01-01 11:00:00
now-1h/d
? now以毫秒为单位舍入到UTC 00:00。解析后为：2001-01-01 00:00:00`
2001.02.01||+1M/d
? 2001.02.1以毫秒格式加一个月。解析后为：2001-03-01 00:00:00
响应过滤（Response Filtering）
所有REST API都接受一个filter_path参数，可以用来减少Elasticsearch返回的响应。该参数采用逗号分隔的以点表示法表示的过滤器列表：
GET /search?q=elasticsearch&filter_path=took，hits.hits.id，hits.hits._score响应
{
"took" : 3,
"hits" : {
"hits" : [
{
"_id" : "0",
"_score" : 1.6375021
}
]
}
}它还支持通配符*来匹配任何字段或字段名称的一部分：
curl -X GET "localhost:9200/_cluster/state?filter_path=metadata.indices.*.stat*"响应
{
"metadata" : {
"indices" : {
"twitter": {"state": "open"}
}
}
}而通配符**可以用来包含字段而无需知道字段的确切路径。例如，我们可以用这个请求返回每个段的Lucene版本信息：
GET /_cluster/state?filter_path=routing_table.indices.**.state响应
{
"routing_table": {
"indices": {
"twitter": {
"shards": {
"0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
}
}
}
}
}也可以通过用char前缀过滤器来排除一个或多个字段-：
curl -X GET "localhost:9200/_count?filter_path=-_shards"响应
{
"count" : 5
}而对于更多的控制，包容性和排他性的过滤器可以组合在同一个表达式中。在这种情况下，首先应用排他性过滤器，并使用包含性过滤器再次过滤结果：
curl -X GET "localhost:9200/_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*"响应
{
"metadata" : {
"indices" : {
"index-1" : {"state" : "open"},
"index-2" : {"state" : "open"},
"index-3" : {"state" : "open"}
}
}
}请注意，Elasticsearch有时直接返回字段的原始值，如_source字段。如果你想过滤_source字段，你应该考虑把已经存在的_source参数（参见Get API 获取更多细节）和filter_path 参数结合起来：
POST /library/book?refresh
{"title": "Book #1", "rating": 200.1}
POST /library/book?refresh
{"title": "Book #2", "rating": 1.7}
POST /library/book?refresh
{"title": "Book #3", "rating": 0.1}
GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc{
"hits" : {
"hits" : [ {
"_source":{"title":"Book #1"}
}, {
"_source":{"title":"Book #2"}
}, {
"_source":{"title":"Book #3"}
} ]
}
}平面设置（Flat Settings）
该flat_settings标志会影响设置列表的呈现。当flat_settings标志为true时返回在一个平面格式：
GET twitter/_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标志是false时返回一个更人类可读的结构化格式：
GET twitter/_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"
}
}
}
}默认情况下flat_settings设置为false。
参数（Parameters）
Rest参数（使用HTTP时，映射到HTTP URL参数）遵循使用下划线框的约定。
布尔值（Boolean Values）
所有REST API参数（请求参数和JSON主体）都支持提供布尔值“false”作为值false，布尔值“true”作为值true。所有其他值将引发错误。
数值（Number Values）
所有REST API都支持在JSON数字类型的基础上将编号参数作为字符串提供。
时间单位（Time units）
无论何时需要指定持续时间，例如对于timeout参数，持续时间必须指定该单位，如2d代表2天。支持的单位如下：
| 单位 | 含义 |
|---|---|
| d | 天 |
| h | 小时 |
| m | 分钟 |
| s | 秒 |
| ms | 毫秒 |
| micros | 微秒 |
| nanos | 纳秒 |
字节大小单位（Byte size units）
每当需要指定数据的字节大小时，例如，设置缓冲区大小参数时，该值必须指定单位，如10千字节为10千字节。请注意，这些单位使用1024的幂，因此1kb表示1024字节。支持的单位是：
| 单位 | 含义 |
|---|---|
| b | 字节 |
| kb | 千字节 |
| mb | 兆字节 |
| gb | 千兆字节 |
| tb | 兆兆字节 |
| pb | 拍字节 |
无单位量化（Unit-less quantities）
无单位数量意味着它们没有“单位”，如“字节”或“赫兹”或“米”或“长吨”。
如果这些数量中的一个很大，我们会将其打印出来，例如10万，10,000,000或7k，7,000。当我们的意思是87时，我们仍会打印87。这些是受支持的乘数：
| 缩写 | 含义 |
|---|---|
| k | Kilo(公斤) |
| m | Mega(兆) |
| g | Giga(千兆) |
| t | Tera(万亿) |
| p | Peta(千兆) |
距离单位（Distance Units）
无论何处需要指定距离，例如地理距离查询中的距离参数，如果未指定距离，则默认单位为米。距离可以在其他单位中指定，例如“1km”或“2mi”（2英里）。
| 名称 | 单位参数 |
|---|---|
| Mile(英里) | mi 或 miles |
| Yard(码) | yd or yards |
| Feet(英尺) | ft or feet |
| Inch(英寸) | in or inch |
| Kilometer(公里) | km or kilometers |
| Meter(米) | m or meters |
| Centimeter(厘米) | cm or centimeters |
| Millimeter(毫米) | mm or millimeters |
| Nautical mile(纳米) | NM, nmi, or nauticalmiles |
模糊性（Fuzziness）
一些查询和API支持使用fuzziness参数进行模糊匹配。
当查询text或keyword字段时，fuzziness被解释为Levenshtein编辑距离 ——一个字符的数量改变，需要对一个字符串进行修改，使其与另一个字符串相同。
该fuzziness参数可以被指定为：
0，1，2
? 最大允许的Levenshtein编辑距离（或编辑数量）
AUTO
? 根据术语的长度生成编辑距离。低距离和高距离参数可以选择提供AUTO:[Low]，[high]，如果没有指定，默认值是3和6，相当于AUTO：3,6：
? 0..2
? 必须完全匹配
? 3..5
? 允许一个编辑距离
? >5
? 允许两个编辑距离
对于fuzziness最好首先使用AUTO。
启用堆栈轨迹（Enabling stack traces）
默认情况下，当请求返回错误时，Elasticsearch不包括错误的堆栈跟踪。您可以通过设置error_traceurl参数为true来启用该行为。例如，默认情况下向_search API 发送无效参数时：
POST /twitter/_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 /twitter/_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]
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"
at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
}
},
"status": 400
}查询字符串中的请求正文（Request body in query string）
对于不接受非POST请求的请求主体的库，您可以将请求主体作为source查询字符串参数进行传递。使用此方法时，source_content_type还应该使用指示源格式的媒体类型值传递该参数，例如application/json。
必要的Content-Type
在请求体中发送的内容类型必须使用Content-Type标头来指定。此标头的值必须映射到API所支持的其中一种格式。大多数API支持JSON，YAML，CBOR和SMILE。批量和多搜索API支持NDJSON，JSON和SMILE; 其他类型将导致错误响应。
此外，使用source查询字符串参数时，必须使用source_content_type查询字符串参数指定内容类型。
基于URL的访问控制（Content-Type Requirements）
许多用户使用基于URL访问控制的代理来保护对Elasticsearch索引的访问。对于multi-search, multi-get, and bulk r请求,用户可以选择在URL中指定一个索引，也可以在请求主体中的每个请求中指定一个索引。这可以使基于URL的访问控制具有挑战性。
为防止用户覆盖URL中指定的索引，请将此设置添加到elasticsearch.yml文件中：
rest.action.multi.allow_explicit_index：false默认值是true，但是当设置false为时，Elasticsearch将拒绝在请求正文中指定具有显式索引的请求。
以上是关于elasticsearch6.7 04.API规范的主要内容，如果未能解决你的问题，请参考以下文章