elasticsearch api约定

elasticsearch REST API 使用JSON经过HTTP协议传输。

本约定贯穿整个REST API，除非有特别的说明。

1、多重索引

大多数APIs引用到一个index参数来在多个索引中执行操做，使用简单的test1,test2,test3标记法（或者_all表示全部索引）。它也支持通配符的方式，例如：test* 或者 *test 或者 te*t 或者 *test*，而且还有“加”和“减”的能力，例如：+test*,-test3。

全部的多索引API都支持下面的url字符查询参数：

ignore_unavailable

控制是否忽略那些不可用的索引，能够指定true 或者 false。

allow_no_indices

控制若是一个通配符索引表达式没有匹配到任何索引时是否失败。能够指定true 或者 false。这个设置也适用于_all，*或者没有指定索引的状况。

expand_wildcards

控制通配符索引表达式的类型。若是是open，只匹配那些打开的索引；若是是closed，只匹配那些关闭的索引

上面这些设置的默认值根据不一样的API是不一样的。

2、索引名称中的Date math支持

Date math索引名称解决方案容许你去搜索一个范围的时间序列索引而不是搜索全部的时间序列索引而后过滤结果或者维护别名。限制搜索索引的数量能够减小集群的负载而且提高执行性能。例如你要在天天的日志中搜索错误，你可使用一个date math名称模版来只搜索过去两天内的索引。

几乎全部的API都拥有一个index参数，支持date math。

一个date math索引名称是以下形式：

<static_name{date_math_expr{date_format|time_zone}}>

属性名	描述
static_name	索引名称的静态部分
date_math_expr	一个动态date math表达式，能够动态计算时间
date_format	可选的日期格式化参数。默认是YYYY.MM.dd
time_zone	可选的时区参数。默认是utc

你必须用尖叫括号围绕date math索引名称表达式，而且全部特殊符号应该被URI编码。例如：

# GET /<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}

部分date math字符编码

特殊字符	URI编码
<	%3C
>	%3E
/	%2F
{	%7B
}	%7D
丨	%7C
+	%2B
:	%3A

注意：|在表格里显式有问题，全部用了一个中文的丨（这是一个汉字）。

下面是一些例子，假设如今是2014年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

下面的例子展现了一个搜索请求搜索过去3天内的日志文件，使用默认的日期格式化样式：

# 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。

格式良好的结果

当在任何请求后面追加?pretty=true会使得返回格式良好的JSON（只限debug！！）。当设置为?format=yaml时结果将会是更可读的yaml格式。

人类可读的输出

统计返回的结果是一种适合人类阅读的格式（例如："exists_time": "1h" 或者 "size": "1kb"），对于计算机是"exists_time_in_millis": 3600000 or "size_in_bytes": 1024。人类可读这个选项能够在查询字符串后添加?human=false来关闭，这个适合统计结果被某种监控工具来使用。同时这也是默认选项。

日期计算

大多数参数接收一个格式化后的日期值，例如gt和lt在范围查询里，或者from和to在日起范围聚合里。

表达式开始于一个锚点日期，能够是now或者以||结尾的日期字符串。这个锚点日期能够随意的追加一个或多个数学表达式组合：

• +1h 增长1小时
• -1d 减小1天
• /d 四舍五入定位到最近的天

支持的时间单位有：

时间单位	描述
y	年
M	月
w	星期
d	天
h	小时（12小时制）
H	小时（24小时制）
m	分钟
s	秒

一些示例：

示例	描述
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参数，它能够用来减小响应的返回字段。参数使用逗号分割而且使用点记法表示：

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

响应值：

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

它也支持*通配符来匹配任何字段或者字段名字的一部分：

GET /_cluster/state?filter_path=metadata.indices.*.stat*

响应值：

{
  "metadata" : {
    "indices" : {
      "twitter": {"state": "open"}
    }
  }
}

**通配符能够在不知道准确字段路径的状况下进行匹配：

GET /_cluster/state?filter_path=routing_table.indices.**.state

响应值：

{
  "routing_table": {
    "indices": {
      "twitter": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "1": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "2": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "3": [{"state": "STARTED"}, {"state": "UNASSIGNED"}],
          "4": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}

还可使用-字符来排除一个或多个字段：

GET /_count?filter_path=-_shards

响应值：

{
  "count" : 5
}

包含和排斥过滤器能够混合使用：

GET /_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参数和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设置

当flat_settings的值是true时，响应将会以flat格式返回：

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。

参数

Rest参数（当使用HTTP时，对应HTTP URL参数）按照约定使用下划线包装。

时间单位

当一个时间段须要被指定时，那么它的单位也必须被指定，好比2d表明2天。支持的单位有：

时间单位	描述
d	天
h	小时
m	分钟
s	秒
ms	毫秒
micros	微秒
nanos	纳秒

字节尺寸单位

有些参数是须要指定字节尺寸的。Elasticsearch支持的单位有：b、kb、mb、gb、tb、pb。

尺寸单位	描述
b	天
kb	小时
mb	分钟
gb	秒
tb	毫秒
pb	微秒

简写单位数量

例如咱们不须要写7000，而能够写7k，支持的乘数有：

乘数	描述
k	千
m	百万
g	十亿
t	兆
p	千兆

启用堆栈跟踪

默认的当一个请求返回一个错误时Elasticsearch不会输出错误的堆栈跟踪信息。你能够经过追加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
}

4、基于URL的访问控制

许多用户使用一个代理进行基于URL的访问控制，来保护对Elasticsearch的索引访问。对于multi-search, multi-get 和 bulk请求，用户能够选择在URL里指定一个索引或者每一个单独的请求体里。这使得基于URL的访问控制很是有挑战性。

为了防止用户从新URL里指定的索引，添加下面的设置到config.yml文件：

rest.action.multi.allow_explicit_index: false

默认值是true，当设置为false时，Elasticsearch将会拒绝一个在请求体中指定索引的请求。