• 文章名稱：Elasticsearch Reference[2.2]
• 原文地址：https://www.elastic.co/guide/en/elasticsearch/reference/2.2/api-conventions.html
• 譯者：code4j

通用選項(xiàng)

以下選項(xiàng)可以用于全部的REST API。

格式化的結(jié)果

當(dāng)任意請(qǐng)求加入?yún)?shù)?pretty=true參數(shù)，返回的JSON將會(huì)被格式化（推薦只在debug的時(shí)候使用！）。另一個(gè)選項(xiàng)設(shè)置參數(shù)為?format=yaml，可以設(shè)置返回結(jié)果是可讀的YAML格式。

人可讀的輸出

統(tǒng)計(jì)數(shù)據(jù)可以返回合適的人可讀的格式（例如"exists_time": "1h" 或 "size": "1kb"）和計(jì)算機(jī)的格式（例如"exists_time_in_millis": 3600000 或 "size_in_bytes": 1024）。人可讀的值可以通過在querystring后面添加?human=false來關(guān)閉。這個(gè)功能在stats結(jié)果提供給監(jiān)控工具而不是給人直接看的時(shí)候比較有意義。human的默認(rèn)值是false。

日期數(shù)學(xué)表達(dá)式

絕大多數(shù)接受格式化的日期值的查詢，例如 range查詢中的 gt 和 lt，或者 daterange 集合中的from和to，都能夠識(shí)別日期數(shù)學(xué)。
表達(dá)式以固定的日期開始，可以是now或者日期字符串，然后以||結(jié)尾。這個(gè)固定的日期后面可以選擇加上一個(gè)或多個(gè)數(shù)學(xué)表達(dá)式。

• +1h - 加一小時(shí)
• -1d - 減一天
• /d - 四舍五入到最近的一天

支持的時(shí)間單位有y (year), M (month), w (week), d (day), h (hour), m (minute), 和 s (second).

展示幾個(gè)示例：

• now+1h - 當(dāng)前時(shí)間加一小時(shí)，毫秒處理
• now+1h+1m - 當(dāng)前時(shí)間加一小時(shí)和一分鐘，毫秒處理
• now+1h/d - 當(dāng)前時(shí)間加一小時(shí)，并四舍五入到最近的一天
• 2015-01-01||+1M/d - 2015-01-01加一個(gè)月，并四舍五入到最近的一天

響應(yīng)過濾器

所有的響應(yīng)都接收一個(gè)filter_path參數(shù)，可以減少elasticsearch的返回結(jié)果。這個(gè)參數(shù)后面跟一組表達(dá)式使用逗號(hào)進(jìn)行分割。

curl -XGET 'localhost:9200/_search?pretty&filter_path=took,hits.hits._id,hits.hits._score'
{

"took" : 3,
"hits" : {
"hits" : [
{
"_id" : "3640",
"_score" : 1.0
},
{
"_id" : "3642",
"_score" : 1.0
}
]
}
}

同樣也接收通配符匹配字段或字段名的一部分。

curl -XGET 'localhost:9200/_nodes/stats?filter_path=nodes..ho'
{
"nodes" : {
"lvJHed8uQQu4brS-SXKsNA" : {
"host" : "portable"
}
}
}

**通配符可用于匹配字段中不確定確切路徑的字段。例如，返回Lucene每個(gè)分片的版本：

curl 'localhost:9200/_segments?pretty&filter_path=indices.**.version'
{
  "indices" : {
    "movies" : {
      "shards" : {
        "0" : [ {
          "segments" : {
            "_0" : {
              "version" : "5.2.0"
            }
          }
        } ],
        "2" : [ {
          "segments" : {
            "_0" : {
              "version" : "5.2.0"
            }
          }
        } ]
      }
    },
    "books" : {
      "shards" : {
        "0" : [ {
          "segments" : {
            "_0" : {
              "version" : "5.2.0"
            }
          }
        } ]
      }
    }
  }
}

注意，Elasticsearch有時(shí)候直接返回一個(gè)字段的原始值，就像_source，如果你想過濾_source字段，你要把filter_path參數(shù)和_source參數(shù)一起用（詳見 Get API）。如下：

curl -XGET 'localhost:9200/_search?pretty&filter_path=hits.hits._source&_source=title'
{
  "hits" : {
    "hits" : [ {
      "_source":{"title":"Book #2"}
    }, {
      "_source":{"title":"Book #1"}
    }, {
      "_source":{"title":"Book #3"}
    } ]
  }
}

展開設(shè)置

flat_settings參數(shù)可以影響settings的渲染效果，當(dāng)設(shè)置flat_settings為true，settings將會(huì)平鋪渲染展示：

{
  "persistent" : { },
  "transient" : {
    "discovery.zen.minimum_master_nodes" : "1"
  }
}

當(dāng)他設(shè)置為fasle的時(shí)候，將會(huì)返回更人性化的結(jié)構(gòu)：

{
  "persistent" : { },
  "transient" : {
    "discovery" : {
      "zen" : {
        "minimum_master_nodes" : "1"
      }
    }
  }
}

默認(rèn)flat_settings是false。

參數(shù)

其余參數(shù)（當(dāng)使用HTTP，HTTP映射到URL的字符串）遵循下劃線約定。

布爾值

所有的REST API（請(qǐng)求體和響應(yīng)JSON）都支持布爾值 false有以下幾種表示方式：false，0，no，off。剩下其他值都是true，注意這個(gè)和入索引的文檔中的字段無關(guān)。

數(shù)值

所有REST API除了原生的JSON數(shù)字類型還支持?jǐn)?shù)字格式的字符串。

時(shí)間單位

無論什么時(shí)候要指定時(shí)間，例如timeout參數(shù)，時(shí)間必須指定單位，比如2d表示兩天，支持的單位如下：

• y - Year （年）
• M - Month（月）
• w - Week（周）
• d - Day（日）
• h - Hour（小時(shí)）
• m - Minute（分鐘）
• s - Second（秒）
• ms - Milli-second（毫秒）

數(shù)據(jù)大小單位

無論什么時(shí)候需要指定數(shù)據(jù)大小，例如設(shè)置緩沖區(qū)大小，單位必須要指定，例如10kb 就是1000字節(jié)。支持的單位如下：

• b - Byte
• kb - 千字節(jié)
• mb - 兆字節(jié)
• gb - GB
• tb - TB
• pb - PB

距離單位

無論什么時(shí)候需要指定距離，例如在Geo Distance Query查詢中使用distance字段，沒指定的情況下默認(rèn)是米，也可以指定其他單位，例如1km或2mi
單位列表如下：

• 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

Geohash Cell Query中的precision（精度）字段可以接受上述距離單位，如果沒有指定，使用geohash的長(zhǎng)度。

模糊行

有些查詢或API支持不精確的模糊匹配，使用fuzziness參數(shù)。fuzziness是上下文敏感的，也就是說這取決于被查詢字段的類型。

數(shù)字，日期和IPV4字段

當(dāng)查詢數(shù)字，日期和IPV4字段時(shí)，fuzziness被解析為+/-，表現(xiàn)和Range Query類似：

-fuzziness <= field value <= +fuzziness

fuzziness字段應(yīng)該使用數(shù)字值，例如2或2.0。date類型應(yīng)該被解析為long值，當(dāng)然也可以用包含時(shí)間的字符串—— “1h” —— 使用時(shí)間單位edit解析。IPV4字段可以接受long值或者另一個(gè)IPV4值（也被解析成long值得IPV4）

String字段

當(dāng)查詢string類型字段，fuzziness使用編輯距離算法解析，一個(gè)字符串的改變可以使一個(gè)字符串等價(jià)于另一個(gè)字符串。
fuzziness參數(shù)可以指定如下值：

• 0, 1, 2 - 最大的編輯距離。
• AUTO 基于term的長(zhǎng)度生成編輯距離，例如長(zhǎng)度在0-2的必須要完全匹配，3-5的可以有一個(gè)字符不同，大于5的可以有兩個(gè)。

通常來說AUTO是fuzziness參數(shù)的首選。

返回結(jié)果風(fēng)格

所有API都接受case參數(shù)。當(dāng)設(shè)置了camelCase，所有的參數(shù)都會(huì)使用駝峰命名，否則是下劃線命名。注意這個(gè)在文檔的source字段中不起作用。

（譯者批注：大概是因?yàn)閟ource是使用者自定義的，而API里面的名字是ES可控的）

query string中的請(qǐng)求體

對(duì)于不接受非POST請(qǐng)求的請(qǐng)求體的庫(kù)，可以將請(qǐng)求體放在query string的source參數(shù)中傳遞。

基于URL的訪問控制

很多用戶使用代理訪和基于URL的訪問控制來確保elasticsearch的索引安全，對(duì)于multi_search，multi_get以及bulk請(qǐng)求，用戶可以在URL中指定索引名，并且還可以在請(qǐng)求體中指定索引名。這樣就基于URL的訪問控制就比較有挑戰(zhàn)了。

為了防止用戶請(qǐng)求體中的索引名覆蓋了URL中的索引名，可以在配置文件中加入如下配置：

rest.action.multi.allow_explicit_index: false

默認(rèn)值是true。但如果配置為false，Elasticsearch就會(huì)拒絕請(qǐng)求體重指明索引名的請(qǐng)求。