Elasticsearch Reference 5.5 中文翻译8

API Conventions

API规范

The elasticsearch REST APIs are exposed using JSON over HTTP.
elasticsearch的REST的API是使用HTTP的JSON格式暴露的。

The conventions listed in this chapter can be applied throughout the REST API, unless otherwise specified.
规范列在这个章节中可以被使用通过REST的API，除非有特殊的规定。

• Multiple Indices
• Date math support in index names
• Common options
• URL-based access control

Multiple Indices

多个索引

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.
大部分API引用一个索引参数支持跨多个索引执行，使用简单的test1、test2、test3通知（或_all用于所有的索引）。他也支持通配符，例如：test*或*test或te*t，并且支持add(+)和remove(-)，例如：+test*、-test3。

All multi indices API support the following url query string parameters:
所有的多个索引API支持如下的URL查询字符串参数:

• ignore_unavailable
• Controls whether to ignore if any specified indices are unavailable, this includes indices that don’t exist or closed indices. Either true or false can be specified.

• 控制是否忽略如果任何指定的索引不可用的话，这包括索引不存在或已关闭的索引。可以指定true或false。

• allow_no_indices

• Controls whether to fail if a wildcard indices expressions results into no concrete indices. Either true or false can be specified. 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. This setting is also applicable when _all, * or no index has been specified. This settings also applies for aliases, in case an alias points to a closed index.

• 控制是否失败如果通配符索引表达式的结果没有指向具体的索引。可以指定true或false。例如如果通配符表达式foo*被指定并且没有可用的索引开始于foo则依赖的这个设置的请求将会失败。这个设置也适用于_all、*或没有指定索引。这个设置也应用于别名，由于别名指向closed的索引。

• expand_wildcards

• 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和close都可以被指定来表达所有的索引。

If none is specified then wildcard expansion will be disabled and if all is specified, wildcard expressions will expand to all indices (this is equivalent to specifying open,closed).
如果通配符表达式指定为none将被关闭并且如果指定为all，通配符表达式将扩展所有的索引（等同于指定open或closed）。

The defaults settings for the above parameters depend on the api being used.
默认的用于上面参数的设置依赖于被使用的api。

Note
注意
Single index APIs such as the Document APIs and the single-index alias APIs do not support multiple indices.
单个索引API例如Document的API和单个索引别名API不在支持多个索引。

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. Limiting the number of indices that are searched reduces the load on the cluster and improves execution performance. For example, if you are searching for errors in your daily logs, you can use a date math name template to restrict the search to the past two days.
数据匹配索引名决定允许你来搜索一定范围时间系列索引，而不是搜索所有的你的时间系列的索引并且过滤结果或维护别名。限制被搜索的索引的数量减少负载集群的负载并且提高执行的效果。例如，如果你在日志中查找错误，你可以使用一个日期匹配模板来限制查询过去的两天。

Almost all APIs that have an index parameter, support date math in the index parameter value.
基本上所有的API有索引参数，支持日期匹配在索引参数值中。

A date math index name takes the following form:
一个日期匹配索引名需要如下的形式：

<static_name{date_math_expr{date_format|time_zone}}>

Where:
其中

|:– |:–|
|static_name |is the static text part of the name 是名字的静态文本部分|
|date_math_expr |is a dynamic date math expression that computes the date dynamically 是动态的日期匹配表达式来动态计算日期|
|date_format |is the optional format in which the computed date should be rendered. Defaults to YYYY.MM.dd. 是可选的格式用于计算应当处理的日期。默认是YYYY.MM.dd|
|time_zone |is the optional time zone . Defaults to utc. 是可选的时区。默认是utc|

You must enclose date math index name expressions within angle brackets, and all special characters should be URI encoded. For example:
你必须处理日期匹配索引名表达式使用尖括号，并且所有指定的字符应当被使用URI编码。例如：

# GET /<logstash-{now/d}>/_searchGET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search{  "query" : {    "match": {      "test": "data"    }  }}

Note
注意
Percent encoding of date math characters
编码日期匹配字符的百分比
The special characters used for date rounding must be URI encoded as follows:
指定的字符用于在URI编码中是如下：

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

The following example shows different forms of date math index names and the final index names they resolve to given the current time is 22rd March 2024 noon utc.
下面的例子展示了不同日期匹配索引名格式和最终的给定的解析索引名对于给定的当前时间2024年三月22日中午。

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&#124;+12:00}}> logstash-2024.03.23

To use the characters { and } in the static part of an index name template, escape them with a backslash , for example:
为了使用字符{和}在索引名模板的静态部分中，使用逃逸字符\，例如：

<elastic\\{ON\\}-{now/M}> resolves to elastic{ON}-2024.03.01 

The following example shows a search request that searches the Logstash indices for the past three days, assuming the indices use the default Logstash index name format, logstash-YYYY.MM.dd.
下面的例子展示了搜索请求索引Logstash索引用于过去的三天，假设索引使用了默认的Logstash索引名格式，logstash-YYYY.MM.dd。

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_searchGET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search{  "query" : {    "match": {      "test": "data"    }  }}

Common options

通用的选项

The following options can be applied to all of the REST APIs.
下面的选项可应用于所有的REST风格的API。

Pretty Results

好的结果

When appending ?pretty=true to any request made, the JSON returned will be pretty formatted (use it for debugging only!). Another option is to set ?format=yaml which will cause the result to be returned in the (sometimes) more readable yaml format.
当添加?pretty=true到任何的请求中，返回的JSON字符串将会是格式化的（只是用于调试）。另一个选项是设置?format=yaml将使得返回的结果是yaml格式的易于读取。

Human readable output

方便阅读的输出

Statistics are returned in a format suitable for humans (eg “exists_time”: “1h” or “size”: “1kb”) and for computers (eg “exists_time_in_millis”: 3600000 or “size_in_bytes”: 1024). The human readable values can be turned off by adding ?human=false to the query string. This makes sense when the stats results are being consumed by a monitoring tool, rather than intended for human consumption. The default for the human flag is false.
返回的状态的格式适合阅读（例如，”exists_time”: “1h” or “size”: “1kb”）并且对于电脑（例如，”exists_time_in_millis”: 3600000 or “size_in_bytes”: 1024）。便于阅读的方式可以被关闭通过添加?human=false到查询的字符串中。这使得状态结果是可以被处理通过监视器工具的，而不是为了方便阅读。默认设置为false。

Date Math

日期的数学

Most parameters which accept a formatted date value — such as gt and lt in range queries range queries, or from and to in daterange aggregations — understand date maths.
大部分参数接收一个格式化的日期值————例如gt和lt用于范围查询或from和to在日期范围聚集————例如日期的数学。

The expression starts with an anchor date, which can either be now, or a date string ending with ||. This anchor date can optionally be followed by one or more maths expressions:
表达式使用一个日期标志开始，可以是now或一个日期字符串使用双竖线结尾。标志日期可是如下的一个或多个数学表达式：

• +1h - add one hour
• 添加一个小时
• -1d - subtract one day
• 减去一天
• /d - round down to the nearest day
• 最接近的天

The supported time units differ from those supported by time units for durations. The supported units are:
支持的时间单位不同于持久化的时间单位。支持的单位是：

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

Some examples are:
一些例子如下：

- - now+1h The current time plus one hour, with ms resolution.
单签时间加上一小时，使用ms解析 now+1h+1m The current time plus one hour plus one minute, with ms resolution.
当前时间加上一小时零一分钟，使用ms解析 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.
2015年1月1日加上一个月，最接近的天

Response Filtering

响应的过滤

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:
所有REST的API接收一个filter_path参数可以被使用来减少elasticsearch的返回。这个参数使用一个逗号分隔列表有关过滤器使用点来表达：

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

Responds:
响应为：

{  "took" : 3,  "hits" : {    "hits" : [      {        "_id" : "0",        "_score" : 1.6375021      }    ]  }}

It also supports the * wildcard character to match any field or part of a field’s name:
他也支持*通配符来匹配任何域或域名的部分：

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

Responds:
响应为：

{  "metadata" : {    "indices" : {      "twitter": {"state": "open"}    }  }}

And the ** wildcard can be used to include fields without knowing the exact path of the field. For example, we can return the Lucene version of every segment with this request:
并且**通配符可以被使用来包含域而不需要指定域的实际路径。例如，我们可以返回Lucene版本对于每个段通过这个请求：

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

Responds:
响应为：

{  "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"}]        }      }    }  }}

It is also possible to exclude one or more fields by prefixing the filter with the char -:
他也可以不包含一个或多个域同前缀过滤器使用字符-：

GET /_count?filter_path=-_shards

Responds:
响应为：

{  "count" : 5}

And for more control, both inclusive and exclusive filters can be combined in the same expression. In this case, the exclusive filters will be applied first and the result will be filtered again using the inclusive filters:
并且为了更好的控制，包含和排除的过滤器可以被组合在相同的表达式中。在这个例子中，排除表达式被首先应用并且记过将再次被过滤使用包含过滤器：

GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

Responds:
响应为：

{  "metadata" : {    "indices" : {      "index-1" : {"state" : "open"},      "index-2" : {"state" : "open"},      "index-3" : {"state" : "open"}    }  }}

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 (see Get API for more details) with the filter_path parameter like this:
注意elasticsearch有时直接返回域的原始数据。例如_source域。如果你希望过滤_source域，你应当考虑合并已有的_source参数（详见Get API）对于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 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:
falt_setting标志影响处理设置的列表。当flat_setting标志为true设置被返回以水平的格式：

GET twitter/_settings?flat_settings=true

Returns:
返回为：

{  "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"    }  }}

When the flat_settings flag is false settings are returned in a more human readable structured format:
当flat_setting标志位false则返回易于阅读的格式：

GET twitter/_settings?flat_settings=false

Returns:
返回为：

{  "twitter" : {    "settings" : {      "index" : {        "number_of_replicas": "1",        "number_of_shards": "1",        "creation_date": "1474389951325",        "uuid": "n6gzFZTgS664GUfx0Xrpjw",        "version": {          "created": ...        },        "provided_name" : "twitter"      }    }  }}

By default the flat_settings is set to false.
默认的flat_setting设置为true。

Parameters

参数

Rest parameters (when using HTTP, map to HTTP URL parameters) follow the convention of using underscore casing.
剩余的参数（当使用HTTP，匹配HTTP的URL参数时）符合使用下划线的格式。

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”.
所有的REST的API参数（请求参数和JSON体）支持提供可以认为是false的值：false、0、no和off。所有其他的值则认为是true。

Warning
警告
Deprecated in 5.3.0.
在5.3.0中被废弃
Usage of any value other than “false” and “true” is deprecated.
使用任何值除了false和true

Number Values

数值

All REST APIs support providing numbered parameters as string on top of supporting the native JSON number types.
所有的REST的API支持提供数值参数作为字符串用于支持本地的JSON数值类型。

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:
指定持续的时间，例如，对于超时参数，持续时间必须指定unit，例如2d用于代表两天。支持的日期单位如下：

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

Byte size units

字节大小单位

Whenever the byte size of data needs to be specified, eg when setting a buffer size parameter, the value must specify the unit, like 10kb for 10 kilobytes. Note that these units use powers of 1024, so 1kb means 1024 bytes. The supported units are:
需要指定的数据的字节大小，例如当设置一个缓冲大小参数，值必须被指定单位，例如10kb代表10k的字节。注意这些单位的使用是以1024为间隔的，因此1kb等于1024字节。支持的单位如下：

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

Unit-less quantities

Unit-less quantities means that they don’t have a “unit” like “bytes” or “Hertz” or “meter” or “long tonne”.
Unit-less quantities意味着他们不需要单位例如bytes或Hertz或meter或long tonne。

If one of these quantities is large we’ll print it out like 10m for 10,000,000 or 7k for 7,000. We’ll still print 87 when we mean 87 though. These are the supported multipliers:
如果quantities中其中一个是很大的我们将会打印为10m代表10,000,000或7k代表7000。我们依然需要打印87当我们需要代表87的时候。这些支持的乘数为：

- - “ Single k Kilo m Mega g Giga t Tera p Peta

Distance Units

距离单位

Wherever distances need to be specified, such as the distance parameter in the Geo Distance Query), the default unit if none is specified is the meter. Distances can be specified in other units, such as “1km” or “2mi” (2 miles).
指定需要的举例，例如distance参数在Geo Distance查询中，默认的单位如果没有指定将会是米。举例可以被指定使用其他的单位，例如1km或2mi（2米）

The full list of units is listed below:
完整的单位列表如下：

- - 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.
有些查询和API支持参数来允许模糊查询，使用fuzziness参数。

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.
当查询文本或关键字域，fuzziness作为Levenshtein Edit Distance————一个字符的数目改变需要被指定对于一个字符串来使得他和其他字符串相同。

The fuzziness parameter can be specified as:
fuzziness参数可以被指定如下：

0, 1, 2    the maximum allowed Levenshtein Edit Distance (or number of edits)       最大允许的Levenshtein编辑举例（或编辑的数目）AUTO    generates an edit distance based on the length of the term. For lengths:      生成一个编辑的举例基于term的长路，例如：      0..2        must match exactly         必须精确匹配    3..5        one edit allowed     >5        two edits allowed    AUTO should generally be the preferred value for fuzziness.    对于fuzziness最好使用AUTO

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. For example, by default when you send an invalid size parameter to the _search API:
默认的当请求返回一个错误Elasticsearch不会包含关于错误的栈追踪信息。你可以开启这个行为通过设置error_trace的url参数为true。例如，默认当你发送一个不合法的参数给_search的API时；

POST /twitter/_search?size=surprise_me

The response looks like:
则响应看起来是这样的：

{  "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}

But if you set error_trace=true:
但是如果你设置error_trace=true，则：

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

The response looks like:
则响应看起来这样的：

{  "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}

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. When using this method, the source_content_type parameter should also be passed with a media type value that indicates the format of the source, such as application/json.
对于库不会接受一个非POST请求带有请求体，你可以传递请求体作为源查询字符串参数作为替代。当使用这个方法时，source_content_type参数应当被传递使用一个媒体类型值指定source的格式，例如application/json。

Content-Type auto-detection

内容类型的自动他侧

Warning
警告
Deprecated in 5.3.0.
在5.3.0中废弃
Provide the proper Content-Type header
提供了Content-Type头信息

The content sent in a request body or using the source query string parameter is inspected to automatically determine the content type (JSON, YAML, SMILE, or CBOR).
在请求体重的内容发送或使用源查询字符串参数代替自动巨鼎当前的类型（JSON、YAML、SMILE或CBOR）。

A strict mode can be enabled which disables auto-detection and requires that all requests with a body have a Content-Type header that maps to a supported format. To enabled this strict mode, add the following setting to the elasticsearch.yml file:
一个严格的模式可以被开启当关闭自动探测和请求所有的请求带有请求体必须有一个Content-Type头信息来匹配支持的格式。为了开启严格模式，添加下面的设置到elasticsearch.yml文件中。

http.content_type.required: true

The default value is false.
默认值为false。

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访问控制来保护对于Elasticsearch索引的访问。对于multi-search、multi-get和bulk请求，用户有选择指定一个在URL中的索引并且独立请求带有请求体。这可以使得基于URL的访问控制遭到挑战。

To prevent the user from overriding the index which has been specified in the URL, add this setting to the elasticsearch.yml file:
为了避免用户覆盖指定在URL中的索引，添加这个设置到elasticsearch.yml文件中：

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.
默认值为true，但是当设置为false时，Elasticsearch将拒绝请求有明确的索引指定在请求体中。