elasticsearch6.7 04.API规范

API Conventions

elasticsearch的REST的API是使用HTTP的JSON格式暴露的。

除非另有说明，本章中列出的约定可以在整个REST API中应用。

• 多索引
• 索引名称支持日期格式的数学运算
• 常规选项
• 基于URL的访问控制

1、多索引

大多数引用index参数的API 支持跨多个索引执行，使用简单的test1,test2,test3符号（或_all用于所有的索引 ）。

它还支持通配符，例如：test*或 *test 或 te*t或*test*，以及“排除”（-）的能力，例如：test*，-test3。

所有多索引API都支持在url中使用以下查询字符串参数：

1.1 ignore_unavailable

​ 控制是否忽略任何指定的索引是否不可用，包括不存在的索引或闭合索引。可以指定true或false。

1.2 allow_no_indices

​ 如果通配符索引表达式导致没有具体索引，则控制是否失败。可以指定true或false。例如，如果指定了通配符表达式 foo 并且没有以 foo 开头的索引，则根据此设置，请求将失败。当指定了 _all，或 no index 时，此设置也适用。如果别名指向封闭索引，则此设置也适用于别名。

1.3 expand_wildcards

​ 控制通配符索引表达式可以扩展到的具体索引类型。如果指定了open，则通配符表达式将扩展为仅打开索引。如果指定closed，则通配符表达式仅扩展为闭合索引。此外，可以指定两个值（open，closed）以扩展到所有索引。

​ 如果none被指定，那么通配符扩展将被禁用，如果all 被指定，通配符表达式将扩展到所有的索引（这相当于指定open,closed）。

上述参数的默认设置取决于正在使用的api。

单个索引API（如Document API 和单索引alias API）不支持多个索引。

2、索引名称支持日期格式的数学运算

日期数学索引名称解析使您能够搜索一系列时间序列索引，而不是搜索所有时间序列索引，并过滤结果或保留别名。限制搜索索引的数量可以减少集群的负载，并提高执行性能。例如，如果要在日常日志中搜索错误，则可以使用日期数学名称模板将搜索限制在过去两天。

几乎所有具有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"
    }
  }
}

3、常规选项

以下选项可以应用于所有REST API。

3.1 格式化相应（Pretty Result）

在任何请求后追加?pretty=true，返回的JSON格式都会非常好（仅用于调试！）。另一个选项是追加

?format=yaml，有时这将导致结果以更可读的yaml格式返回。

3.2 人类可读式输出（Human readable output）

统计数据以适合人类（例如"exists_time": “1h"或"size”: “1kb”）和计算机（例如"exists_time_in_millis": 3600000或"size_in_bytes": 1024）的格式返回。可以通过添加“?human=false“查询字符串来关闭可读取的值。当统计结果被监测工具消耗时，这是有意义的，而不是用于人类消耗。human标志的默认值是 false。

3.3 日期数学（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"}
    } ]
  }
}

3.4 平面设置（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。

3.5 参数（Parameters）

Rest参数（使用HTTP时，映射到HTTP URL参数）遵循使用下划线框的约定。

3.6 布尔值（Boolean Values）

所有REST API参数（请求参数和JSON主体）都支持提供布尔值“false”作为值false，布尔值“true”作为值true。所有其他值将引发错误。

3.7 数值（Number Values）

所有REST API都支持在JSON数字类型的基础上将编号参数作为字符串提供。

3.8 时间单位（Time units）

无论何时需要指定持续时间，例如对于timeout参数，持续时间必须指定该单位，如2d代表2天。支持的单位如下：

单位	含义
d	天
h	小时
m	分钟
s	秒
ms	毫秒
micros	微秒
nanos	纳秒

3.9 字节大小单位（Byte size units）

每当需要指定数据的字节大小时，例如，设置缓冲区大小参数时，该值必须指定单位，如10千字节为10千字节。请注意，这些单位使用1024的幂，因此1kb表示1024字节。支持的单位是：

单位	含义
b	字节
kb	千字节
mb	兆字节
gb	千兆字节
tb	兆兆字节
pb	拍字节

3.10 无单位量化（Unit-less quantities）

无单位数量意味着它们没有“单位”，如“字节”或“赫兹”或“米”或“长吨”。

如果这些数量中的一个很大，我们会将其打印出来，例如10万，10,000,000或7k，7,000。当我们的意思是87时，我们仍会打印87。这些是受支持的乘数：

缩写	含义
k	Kilo(公斤)
m	Mega(兆)
g	Giga(千兆)
t	Tera(万亿)
p	Peta(千兆)

3.11 距离单位（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

3.12 模糊性（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。

3.13 启用堆栈轨迹（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]\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
}

3.14 查询字符串中的请求正文（Request body in query string）

对于不接受非POST请求的请求主体的库，您可以将请求主体作为source查询字符串参数进行传递。使用此方法时，source_content_type还应该使用指示源格式的媒体类型值传递该参数，例如application/json。

3.15 必要的Content-Type

在请求体中发送的内容类型必须使用Content-Type标头来指定。此标头的值必须映射到API所支持的其中一种格式。大多数API支持JSON，YAML，CBOR和SMILE。批量和多搜索API支持NDJSON，JSON和SMILE; 其他类型将导致错误响应。

此外，使用source查询字符串参数时，必须使用source_content_type查询字符串参数指定内容类型。

4、基于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将拒绝在请求正文中指定具有显式索引的请求。