Elasticsearch7.1中文文檔-第四章-API約定

Elasticsearch REST APIs是用HTTP暴露的，而且是基於JSON的。

除非另有說明，不然本章中的約定均可以使用REST API來使用。

• 多索引
• 索引名稱中支持日期數學
• 公用選項
• 基於URL的訪問控制

多索引

大多數引用index參數的api支持跨多個索引執行，使用簡單的test1，test2，test3表示法（或_all表示全部索引）。

全部多索引API都支持下面的url查詢字符串參數：

ignore_unavailable	若是指定索引是不可用的，控制是否忽略該索引。包括b不存在的索引和已關閉(closed)的索引，能夠指定ture或者false
allow_no_indices	通配符索引表達式沒有具體的索引時，控制結果是否失敗。能夠指定true或false。例如，若是指定通配符表達式foo*，而且沒有以foo開頭的索引可用，請求將失敗。當_all、*或沒有指定索引時，此設置也適用。此設置也適用於別名，以防別名指向已關閉（closed）索引。
expand_wildcards	控制通配符索引表達式能夠擴展爲什麼種具體索引。若是指定了open，則通配符表達式將擴展爲僅打開索引。若是指定了closed，則通配符表達式僅擴展到封閉索引。還能夠指定這兩個值(open和closed)擴展到全部索引。

上述參數的默認設置取決於所使用的API。

與多索引API相對的是單索引API，例如DocumentAPI和aliasAPI就不支持多索引。

索引名稱中支持日期數學

日期數學索引名稱解析可讓你搜索一段time-series區間的索引，而不是搜索全部time-series索引並過濾結果或維護別名。限制搜索索引的數量能夠減小集羣上的負載並提升執行性能。例如，若是在平常日誌中搜索錯誤，可使用date math name模板將搜索限制在過去兩天。

幾乎全部具備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

注意在date_format中使用小寫字母vs大寫字母。例如:mm表示每小時的分鐘，而mm表示一年的月份。一樣，hh表示1-12小時範圍內的小時與AM/PM相結合，而hh表示0-23 24小時範圍內的小時。

注意date_format中小寫和大寫字母的使用。 例如：mm表示分鐘，而MM表示一年中的月份。 相似地，hh表示1-12範圍內的小時與AM / PM的組合，而HH表示0-23小時範圍內的小時。

日期數學表達式與區域時間無關。 所以，除了公曆以外，不可能使用任何其餘日曆。

必須將date math索引名稱表達式括在大括號內，而且全部特殊字符都應該是URI編碼的。例如:

# GET /<logstash-{now/d}>/_search
curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
'
複製代碼

date math 字符對應的編碼

日期的括號，必須使用URI編碼，可參照下表：

<	%3C
>	%3E
/	%2F
{	%7B
}	%7D
|	%7C
+	%2B
:	%3A
,	%2C

下面的示例顯示了不一樣形式的日期數學索引名，它們根據當前時間解析的最終索引名是22nd March 2024 noon utc。

Expression	Resolves to
<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
curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
'
複製代碼

公用選項

下面全部的選項能夠用在全部的API上。

美化的結果

當對請求添加pretty = true時，返回的JSON將被格式化（僅用於調試！）。 另外一種選擇是設置format = yaml，這將致使以可讀的yaml格式返回結果。

可讀的輸出

統計以可讀的格式（例如「exists_time」：「1h」或「size」：「1kb」）和計算機（例如「exists_time_in_millis」：3600000或「size_in_bytes」：1024）返回。 能夠經過向查詢字符串添加human = false來關閉可讀取的格式。 當統計結果被監視工具使用而不是供人使用時。默認值爲false。

日期數學（Date Math）

大多數參數接受一個格式化的日期值，例如在range查詢的gt和lt，或者daterange聚合中的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 以毫秒爲單位減去1小時, 四捨五入到UTC 00:00.結果爲: 2001-01-01 00:00:00
2001.02.01\|\|+1M/d	2001-02-01 以毫秒爲單位加一個月. 結果爲: 2001-03-01 00:00:00

響應過濾

全部的REST API均可以接受filter_path參數，能夠用來減小響應的返回，此參數採用逗號分隔的過濾器列表，用點表示法表示：

curl -X GET "localhost:9200/_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版本：

curl -X GET "localhost:9200/_cluster/state?filter_path=routing_table.indices.**.state"
複製代碼

響應結果：

{
  "routing_table": {
    "indices": {
      "twitter": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}

複製代碼

也能夠經過在過濾器前面添加-來排除一個或多個字段

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參數與filter_path參數組合起來，以下所示:

curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #1", "rating": 200.1}
'
curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #2", "rating": 1.7}
'
curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #3", "rating": 0.1}
'
curl -X GET "localhost:9200/_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標誌會影響設置列表的呈現。 當flat_settings標誌爲true時，將以以下格式返回設置：

curl -X GET "localhost:9200/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.

參數

REST參數（使用HTTP時，映射到HTTP URL參數）遵循使用下劃線框的約定。

布爾值

全部的REST API參數（請求參數和JSON主體）都支持提供布爾值「false」做爲值false，布爾值「true」做爲值true。 全部其餘值都會引起錯誤。

數值

全部REST api都支持以字符串的形式提供參數（這個字符串必須符合數字格式，例如不能是12a）。

時間單位

當須要指定持續時間時，例如對於超時參數，持續時間必須指定單位，好比2d，持續2天。支持單位包括:

d	天
h	時
m	分
s	秒
ms	毫秒
micros	微秒
nanos	納秒

字節大小單位

每當須要指定數據的字節大小時，例如， 設置緩衝區大小參數時，該值必須指定單位，如10千字節爲10千字節。 請注意，這些單位使用1024的冪，所以1kb表示1024字節。 支持的單位是：

b	Bytes
kb	Kilobytes
mb	Megabytes
gb	Gigabytes
tb	Terabytes
pb	Petabytes

無單位數量

無單位數量意味着它們沒有「單位」，如「字節」、「赫茲」、「米」或「噸」。

若是這些量中有一個很大，咱們將打印出來，好比10m(10,000,000)或7k(7000)。當咱們的意思是87時，咱們仍然會打印87。這些是支持的乘數:

k	Kilo
m	Mega
g	Giga
t	Tera
p	Peta

距離單位

在須要指定距離的地方，好比地理距離查詢中的距離參數，若是沒有指定距離，默認單位是米。距離能夠用其餘單位表示，如「1km」或「2mi」(2英里)。

Mile	mi or 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（納米）

模糊

一些查詢和api支持使用模糊參數進行模糊匹配。

當查詢text或keyword字段時，模糊性被解釋爲Levenshtein編輯距離——須要對一個字符串進行的字符數更改，以使其與另外一個字符串相同。

fuzziness能夠被指定爲：

0, 1, 2	最大容許的 Levenshtein Edit Distance (或者編輯數)
AUTO	根據術語的長度生成編輯距離。 可選擇提供低距離和高距離參數AUTO:[low],[high]。 若是未指定，則默認值爲3和6，至關於AUTO:3,6表示長度： 0..2 必須徹底匹配 3..5 容許一次編輯 >5 容許兩次編輯 AUTO一般應該是模糊的首選值。

啓用堆棧跟蹤

當請求時返回一個錯誤，默認狀況下，Elasticsearch不會包含錯誤的堆棧跟蹤。你能夠經過設置error_traceurl參數爲truel來啓用堆棧跟蹤，例如：默認的，當你發送一個無效的size給_searchAPI:

curl -X POST "localhost:9200/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

curl -X POST "localhost:9200/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
}

複製代碼

請求體在查詢字符串中

對於不接受非post請求的請求體的庫，能夠將請求體做爲source查詢字符串參數傳遞。當使用此方法時，source_content_type參數還應該與指示源格式的媒體類型一塊兒傳遞，例如application/json。

Content-Type要求

必須使用Content-Type請求頭指定請求體中發送的內容類型。Content-type的值必須是API支持格式之一。大多數api支持JSON、YAML、CBOR和SMILE。批量和多搜索api支持NDJSON、JSON和SMILE;其餘類型將致使錯誤響應。

或者，當咱們使用source查詢字符串參數，必須使用source_content_type指定Content-Type。

基於URL的訪問控制

許多用戶使用基於url的訪問控制代理來確保對Elasticsearch索引的訪問。對於多搜索、多獲取和批量請求，用戶能夠選擇在URL中指定索引，也能夠選擇在請求體中指定每一個請求的索引。

要防止用戶覆蓋URL中指定的索引，請將此設置添加到elasticsearch.yml文件中:

rest.action.multi.allow_explicit_index: false

複製代碼

默認值爲true，可是當你設置爲false，Elasticsearch將拒絕在請求體中指定顯式索引的請求。