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將會拒絕一個在請求體中指定索引的請求。