Elastic API规范

Elasticsearch的REST API通过HTTP协议以JSON的格式开放出来

本章节中列举的规范，适用于所有的REST API，除非特别说明


== 多索引 ==

大部分API操作的索引参数都支持跨多个索引，使用例如 test1,test2,test3 标记法，或使用 _all 表示全部索引，也支持通配符，例如 test*,*test 或 *test*，还有包含“add(+)”和“移除(-)”的能力，例如 +test*,-test3 表示操作所有名称以test开头的索引，但排除test3

所有多索引API都支持以下URL查询选项：

- ignore_unavailable
  如果指定的索引不可用是否自动忽略，例如该索引不存在或已关闭，可用值为true或false

- allow_no_indices
  是否允许指定的通配符匹配不到具体的索引，可用值为true或false，例如指定了foo*通配表达式，但没有可用的索引是以foo开头的，此时该操作是否失败，该选项也作用于 _all、* 或未指定索引的情况，还作用于别名(aliase)，例如一个别名指向一个已关闭的索引

- expand_wildcards
  控制通配符扩展的索引类型，如果值为open，通配符只会匹配处于打开状态的索引，如果值为closed，则只会匹配关闭的索引，可以设置为 open,closed 或 all，表示匹配所有索引，还能设置为none，表示禁用通配符匹配

以上3个选项的默认值，取决于每个具体的API


== 索引名支持日期计算 ==

可以搜索以时间序列命名的一批索引，而不是频繁修改查询语句或维护别名，限定搜索的索引个数可降低集群负载，并提升执行性能，例如，在每天的日志文件中搜索错误信息，可使用日期计算模板限定只搜索近两天的索引

几乎所有API的索引参数都支持日期计算，类似于以下格式：



其中：
- static_name 是索引名的静态文本部分
- date_math_expr 是日期计算表达式，索引名的动态计算部分
- date_format 是计算出的日期格式，默认为YYYY.MM.dd
- time_zone 是可选的时区，默认为utc

必须使用尖括号包围整个日期计算表达式，并将特殊字符写成URI编码，例如：

$ curl -XGET '' -d '{"query":{"match":{"test":"data"}}}'

要写成如下形式：

$ curl -XGET '%3Clogstash-%7Bnow%2Fd%7D%3E/_search' -d '{"query":{"match":{"test":"data"}}}'

相关字符的URI编码表：
  <    %3C
  >    %3E
  /    %2F
  {    %7B
  }    %7D
  |    %7C
  +    %2B
  :    %3A
  ,    %2C

以下例子展示不同格式的日期计算表达式和对应的索引名，日期时间为2024-03-22 12:00:00 UTC

                       当前日期    logstash-2024.03.22
                       当前月份    logstash-2024.03.01
              只要年月    logstash-2024.03
           上一个月    logstash-2024.02
    12小时后    logstash-2024.03.23

如要在索引名的静态部分使用花括号{和}，要使用反斜杠\逃逸它们，例如 解析结果为 elastic{ON}-2024.03.01

下例展示搜索近三天的logstash开头的索引请求：

$ curl -XGET ',,/_search' -d '{
  "query": { "match": { "test": "data" } }
}'

转换成URI编码为：

$ curl -XGET '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search' -d '{
  "query": { "match": { "test": "data" } }
}'


== 常用选项 ==

以下选项可应用在所有REST API上

【美化返回结果】

在请求URL后附加 ?pretty=true，JSON结果将以美观格式返回，另一个选项是 ?format=yaml，结果将以更可读的YAML格式返回

【可阅读格式输出】

在默认情况下，或请求URL后附加 ?human=false 时，统计信息以适用于计算的方法返回，例如 "exists_time_in_millis": 3600000 或 "size_in_bytes": 1024，这利于监控工具的计算，当在请求URL后附加 ?human=true 时，统计信息以适合人类阅读的格式返回，例如 "exists_time": "1h" 或 "size": "1kb"

【日期计算】

多数参数都接受格式化的日期数据，例如范围查询中的gt和lt，或分页中的from和to，都能理解日期计算

表达式以待计算的日期开头，可以是now，表示当前日期时间，或是以||结尾的日期字符串，还能选用以下一个或多个计算表达式：

  +1h  加1小时
  -1d  减1天
  /d   最近的日期

支持的时间单位有：

  y  years
  M  months
  w  weeks
  d  days
  h  hours
  H  hours
  m  minutes
  s  seconds

一些例子如下：

  now+1h             当前时间加1小时后的毫秒数
  now+1h+1m          当前时间加1小时再加1分钟后的毫秒数
  now+1h/d           当前时间加1小时后的日期
  2015-01-01||+1M/d  2015-01-01加1个月后的日期

【应答过滤】

所有REST API都接受 filter_path 过滤参数，可用于指定Elasticsearch应答的返回内容，该参数接受一个以逗号分隔的一连串点标记过滤表达式，例如：

$ curl -XGET '172.16.88.31:9200/bank/account/_search?pretty&filter_path=hits.total,hits.hits._score,hits.hits._source.account_number' -d '{"query":{"match":{"address" : "671 Bristol Street"}}}'

返回结果为：
{
  "hits" : {
    "total" : 2,
    "hits" : [
      {
        "_score" : 0.7594807,
        "_source" : {
          "account_number" : 6
        }
      },
      {
        "_score" : 0.6099695,
        "_source" : {
          "account_number" : 13
        }
      }
    ]
  }
}
hits中只有filter_path指定的列

也可用统配符*匹配任意字段或字段名，例如：

$ curl -XGET '172.16.88.31:9200/bank/account/_search?pretty&filter_path=hits.total,hits.hits._score,hits.hits._source.*name' -d '{"query":{"match":{"address" : "671 Bristol Street"}}}'

返回结果为：
{
  "hits" : {
    "total" : 2,
    "hits" : [
      {
        "_score" : 0.7594807,
        "_source" : {
          "firstname" : "Hattie",
          "lastname" : "Bond"
        }
      },
      {
        "_score" : 0.6099695,
        "_source" : {
          "firstname" : "Nanette",
          "lastname" : "Bates"
        }
      }
    ]
  }
}

通配符**用于省略多层，如上例的 hits.hits._source.*name 可改写为 hits.**.*name，如此还能匹配到 hits.hits._source.education.schoolname

也可用以字符-为前缀的过滤器来排除一个或多个字段，例如：

$ curl -XGET '172.16.88.31:9200/bank/account/_count?pretty&filter_path=-_shards'

返回结果为：
{
  "count" : 3
}

在一个表达式中，当包含过滤器和排除过滤器同时出现时，排除过滤先被应用，得到执行结果后再应用包含过滤器提取字段

【时间单位】

某些用时参数（如timeout）需要指定度量单位，类似2d为2天，所有可用单位如下：

  d       天
  h       时
  m       分
  s       秒
  ms      毫秒
  micros  微秒
  nanos   纳秒

【距离单位】

某些距离参数（如distance）需要指定度量单位，当不指定时默认为米(meter)，所有可用单位有：

  in   英寸
  ft   英尺
  mi   英里
  yd   码
  mm   毫米
  cm   厘米
  m    米
  km   千米
  nmi  海里


== 基于URL的访问控制 ==

例如multi-search、multi-get和bulk请求，用户既可以在URL中指定索引，也可以在请求体(body)里为每个操作单独指定索引，这对基于URL的访问控制带来了挑战

为防止用户覆盖URL中指定的索引，可在config.yml文件中增加如下配置项：

rest.action.multi.allow_explicit_index: false

默认值为true，当设置为false时，Elasticsearch将拒绝执行在请求体中指定索引的请求