根据原文翻译整理
https://www.elastic.co/guide/en/elasticsearch/reference/5.0/api-conventions.html



The elasticsearch REST APIs are exposed using JSON over HTTP.
The conventions listed in this chapter can be applied throughout the REST API, 
unless otherwise specified.

API 约定
Multiple Indices   
Date math support in index names
Common options
URL-based access control


Most APIs that refer to an index parameter support execution across multiple indices, 
using simple test1,test2,test3 notation (or _all for all indices). 
It also support wildcards, for example: test* or *test or te*t or *test*, 
and the ability to "add" (+) and "remove" (-), for example: +test*,-test3.

支持在多个索引上操作

All multi indices API support the following url query string parameters:

ignore_unavailable
是否忽略不存在的活关闭的索引 true or false

allow_no_indices


expand_wildcards
Controls whether to fail if a wildcard indices expressions results into no concrete indices. 
控制通配符索引表达式导致没有具体索引，则是否失败。可以指定true或false
 For example if the wildcard expression foo* is specified 
 and no indices are available that start with foo 
 then depending on this setting the request will fail.
 
 例如，如果通配符表达式foo*被指定，并且没有以foo开头的索引可用，那么根据这个设置，请求将失败
  
 


Controls to what kind of concrete indices wildcard indices expression expand to. 
If open is specified then the wildcard expression is expanded to only open indices 
and if closed is specified then the wildcard expression is expanded only to closed indices. 
Also both values (open,closed) can be specified to expand to all indices.

控件扩展到何种具体索引通配符索引表达式。
如果指定了open，那么通配符表达式将只扩展到open索引，
如果指定了closed，那么通配符表达式将只扩展到closed索引。
也可以指定两个值(open和closed)来展开到所有索引。



Single index APIs such as the Document APIs and the single-index alias APIs do not support multiple indices.


Date math support in index names

Date math index name resolution enables you to search a range of time-series indices, 
rather than searching all of your time-series indices and filtering the results or maintaining aliases.

Date math索引名称解析能够搜索一系列时间序列索引，而不是搜索所有时间序列索引并过滤结果或维护别名

You must enclose date math index name expressions within angle brackets, 
and all special characters should be URI encoded.

日期索引表达式放在尖括号中，并做URL编码

//_search
/%3Clogstash-%7Bnow%2Fd%7D%3E/_search

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


<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}> resolves to elastic{ON}-2024.03.01




backslash 反斜杆转义


Common options 常用选项

Pretty Results

?pretty=true

Human readable output

?human=false  
The default for the human flag is false.
"exists_time": "1h" or "size": "1kb"

Date Math

+1h - add one hour
-1d - subtract one day
/d - round down to the nearest day

y years
M months
w weeks
d days
h hours
H hours
m minutes
s seconds


now+1h
The current time plus one hour, with ms resolution.

now+1h+1m
The current time plus one hour plus one minute, with ms resolution.

now+1h/d
The current time plus one hour, rounded down to the nearest day.

2015-01-01||+1M/d
2015-01-01 plus one month, rounded down to the nearest day.


Response Filtering

filter_path  返回结果字段过滤

All REST APIs accept a filter_path parameter that can be used to reduce the response returned by elasticsearch. 
This parameter takes a comma separated list of filters expressed with the dot notation:

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

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

It is also possible to exclude one or more fields by prefixing the filter with the char -:
GET /_count?filter_path=-_shards

排除指定字段

And for more control, both inclusive and exclusive filters can be combined in the same expression. 
GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

包含和排除组合使用

Note that elasticsearch sometimes returns directly the raw value of a field, 
like the _source field. If you want to filter _source fields, 
you should consider combining the already existing _source parameter 

_source 字段过滤

GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc


Flat Settings
The flat_settings flag affects rendering of the lists of settings. 
When flat_settings flag is true settings are returned in a flat format:

GET twitter/_settings?flat_settings=true

当flat_settings标志为true时，以平面格式返回设置


Boolean Values
All REST APIs parameters (both request parameters and JSON body) support providing boolean "false" 
as the values: false, 0, no and off. All other values are considered "true". 
Note, this is not related to fields within a document indexed treated as boolean fields.

number values 

Time units

Whenever durations need to be specified, e.g. for a timeout parameter, 
the duration must specify the unit, like 2d for 2 days. The supported units are:

d days
h hours
m minutes
s seconds
ms milliseconds
micros microseconds
nanos nanoseconds


Byte size units

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


Unit-less quantities
10m for 10,000,000 or 7k for 7,000

k Kilo
m Mega
g Giga
t Tera
p Peta

Distance Units
Geo Distance Query
 
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



Fuzziness
模糊匹配

Some queries and APIs support parameters to allow inexact fuzzy matching, using the fuzziness parameter.
When querying text or keyword fields, fuzziness is interpreted as a Levenshtein Edit Distance 
 the number of one character changes that need to be made to one string to make it the same as another string.

Levenshtein编辑距离

The fuzziness parameter can be specified as:

0, 1, 2
the maximum allowed Levenshtein Edit Distance (or number of edits)
AUTO
generates an edit distance based on the length of the term. For lengths:
0..2 must match exactly
3..5 one edit allowed
>5 two edits allowed





Enabling stack traces

By default when a request returns an error Elasticsearch doesn’t include the stack trace of the error. 
You can enable that behavior by setting the error_trace url parameter to true

POST /twitter/_search?size=surprise_me&error_trace=true




Request body in query string
For libraries that don’t accept a request body for non-POST requests, 
you can pass the request body as the source query string parameter instead.




URL-based access control
基于url的权限控制

Many users use a proxy with URL-based access control to secure access to Elasticsearch indices. 
For multi-search, multi-get and bulk requests, the user has the choice of specifying an index in the URL 
and on each individual request within the request body. 
This can make URL-based access control challenging.

许多用户使用基于url的访问控制代理来保护对ES索引的访问。
对于多搜索、多get和批量请求，用户可以选择在URL中指定索引，以及在请求体中的每个单独请求上指定索引。
这给基于url的访问控制带来了挑战。


To prevent the user from overriding the index which has been specified in the URL, 
add this setting to the config.yml file:

rest.action.multi.allow_explicit_index: false

The default value is true, but when set to false, 
Elasticsearch will reject requests that have an explicit index specified in the request body.

防止用户覆盖URL中指定的索引，可以设置 rest.action.multi.allow_explicit_index 为 false 

拒绝在请求体中指定显式索引的请求