- 文章名称：Elasticsearch Reference[2.2]
- 原文地址：https://www.elastic.co/guide/en/elasticsearch/reference/2.2/api-conventions.html
- 译者：code4j
通用选项
以下选项可以用于全部的REST API。
格式化的结果
当任意请求加入参数?pretty=true参数，返回的JSON将会被格式化（推荐只在debug的时候使用！）。另一个选项设置参数为?format=yaml，可以设置返回结果是可读的YAML格式。
人可读的输出
统计数据可以返回合适的人可读的格式（例如"exists_time": "1h" 或 "size": "1kb"）和计算机的格式（例如"exists_time_in_millis": 3600000 或 "size_in_bytes": 1024）。人可读的值可以通过在querystring后面添加?human=false来关闭。这个功能在stats结果提供给监控工具而不是给人直接看的时候比较有意义。human的默认值是false。
日期数学表达式
绝大多数接受格式化的日期值的查询，例如 range查询中的 gt 和 lt，或者 daterange 集合中的from和to，都能够识别日期数学。
表达式以固定的日期开始，可以是now或者日期字符串，然后以||结尾。这个固定的日期后面可以选择加上一个或多个数学表达式。
- +1h - 加一小时
- -1d - 减一天
- /d - 四舍五入到最近的一天
支持的时间单位有y (year), M (month), w (week), d (day), h (hour), m (minute), 和 s (second).
展示几个示例：
-
now+1h- 当前时间加一小时，毫秒处理 -
now+1h+1m- 当前时间加一小时和一分钟，毫秒处理 -
now+1h/d- 当前时间加一小时，并四舍五入到最近的一天 -
2015-01-01||+1M/d-2015-01-01加一个月，并四舍五入到最近的一天
响应过滤器
所有的响应都接收一个filter_path参数，可以减少elasticsearch的返回结果。这个参数后面跟一组表达式使用逗号进行分割。
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每个分片的版本：
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有时候直接返回一个字段的原始值，就像_source，如果你想过滤_source字段，你要把filter_path参数和_source参数一起用（详见 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"}
} ]
}
}
展开设置
flat_settings参数可以影响settings的渲染效果，当设置flat_settings为true，settings将会平铺渲染展示：
{
"persistent" : { },
"transient" : {
"discovery.zen.minimum_master_nodes" : "1"
}
}
当他设置为fasle的时候，将会返回更人性化的结构：
{
"persistent" : { },
"transient" : {
"discovery" : {
"zen" : {
"minimum_master_nodes" : "1"
}
}
}
}
默认flat_settings是false。
参数
其余参数（当使用HTTP，HTTP映射到URL的字符串）遵循下划线约定。
布尔值
所有的REST API（请求体和响应JSON）都支持布尔值 false有以下几种表示方式：false，0，no，off。剩下其他值都是true，注意这个和入索引的文档中的字段无关。
数值
所有REST API除了原生的JSON数字类型还支持数字格式的字符串。
时间单位
无论什么时候要指定时间，例如timeout参数，时间必须指定单位，比如2d表示两天，支持的单位如下：
-
y- Year （年） -
M- Month（月） -
w- Week（周） -
d- Day（日） -
h- Hour（小时） -
m- Minute（分钟） -
s- Second（秒） -
ms- Milli-second（毫秒）
数据大小单位
无论什么时候需要指定数据大小，例如设置缓冲区大小，单位必须要指定，例如10kb 就是1000字节。支持的单位如下：
-
b- Byte -
kb- 千字节 -
mb- 兆字节 -
gb- GB -
tb- TB -
pb- PB
距离单位
无论什么时候需要指定距离，例如在Geo Distance Query查询中使用distance字段，没指定的情况下默认是米，也可以指定其他单位，例如1km或2mi
单位列表如下：
- Mile -
miormiles - Yard -
ydoryards - Feet -
ftorfeet - Inch -
inorinch - Kilometer -
kmorkilometers - Meter -
mormeters - Centimeter -
cmorcentimeters - Millimeter -
mmormillimeters - Nautical mile -
NM,nmiornauticalmiles
Geohash Cell Query中的precision（精度）字段可以接受上述距离单位，如果没有指定，使用geohash的长度。
模糊行
有些查询或API支持不精确的模糊匹配，使用fuzziness参数。fuzziness是上下文敏感的，也就是说这取决于被查询字段的类型。
数字，日期和IPV4字段
当查询数字，日期和IPV4字段时，fuzziness被解析为+/-，表现和Range Query类似：
-fuzziness <= field value <= +fuzziness
fuzziness字段应该使用数字值，例如2或2.0。date类型应该被解析为long值，当然也可以用包含时间的字符串—— “1h” —— 使用时间单位edit解析。IPV4字段可以接受long值或者另一个IPV4值（也被解析成long值得IPV4）
String字段
当查询string类型字段，fuzziness使用编辑距离算法解析，一个字符串的改变可以使一个字符串等价于另一个字符串。
fuzziness参数可以指定如下值：
-
0,1,2- 最大的编辑距离。 -
AUTO基于term的长度生成编辑距离，例如长度在0-2的必须要完全匹配，3-5的可以有一个字符不同，大于5的可以有两个。
通常来说AUTO是fuzziness参数的首选。
返回结果风格
所有API都接受case参数。当设置了camelCase，所有的参数都会使用驼峰命名，否则是下划线命名。注意这个在文档的source字段中不起作用。
（译者批注：大概是因为source是使用者自定义的，而API里面的名字是ES可控的）
query string中的请求体
对于不接受非POST请求的请求体的库，可以将请求体放在query string的source参数中传递。
基于URL的访问控制
很多用户使用代理访和基于URL的访问控制来确保elasticsearch的索引安全，对于multi_search，multi_get以及bulk请求，用户可以在URL中指定索引名，并且还可以在请求体中指定索引名。这样就基于URL的访问控制就比较有挑战了。
为了防止用户请求体中的索引名覆盖了URL中的索引名，可以在配置文件中加入如下配置：
rest.action.multi.allow_explicit_index: false
默认值是true。但如果配置为false，Elasticsearch就会拒绝请求体重指明索引名的请求。
