Elasticsearch7.x——Rest API通用参数详解

Rest API通用参数

1、多索引

大多数API都支持跨多个索引执行，可以使用简单的test1,test2,test3表示法(或对所有索引执行，用_all)。它还支持通配符，例如test*或*test或te*t或*test*，以及“排除”(-)功能，例如-test3。

所有多索引API都支持以下URL查询字符串参数:

ignore_unavailable ：控制是否忽略不可用索引，包括不存在的索引或已关闭的索引。可以设置为true或false。
allow_no_indices ：当通配符索引表达式结果为空时，allow_no_indices控制请求是否失败。可以指定true或false。例如，指定了通配符表达式foo*却没有以foo开头的索引可用，如果此设置为true，请求将失败。当未指定 _all、*或无索引时，此设置也适用。此设置也适用于别名，以防别名指向关闭的索引。
expand_wildcards ：控制通配符索引表达式可以扩展到哪种具体索引。
- all：包括open、closed和hidden
- open：通配符表达式将扩展为仅打开索引。
- closed：通配符表达式仅扩展为closed索引
- hidden：通配符的扩展将包括隐藏索引。必须与open、closed或两者结合使用。
- none：不接受通配符表达式。
ignore_throttled ：如果为true，则忽略具体索引、扩展索引或别名索引。

2、日期数学格式

索引名称支持日期解析，这样能够搜索一个时间范围内或某几段时间内的索引，而不是搜索所有索引再筛选结果或维护别名。限制搜索的索引数量可以减少集群上的负载并提高执行性能。例如，如果在日常日志中搜索错误信息，可以使用日期格式名称模板将搜索严格限制在过去两天内。

几乎所有具有index参数的API都支持index参数值中包含日期数学格式。日期数学索引名称具有以下形式:

    <static_name{date_math_expr{date_format|time_zone}}>

static_name ：索引名称的静态文本部分。
date_math_expr ：动态日期数学表达式，用于动态计算日期。
date_format ：用来设置日期的可选格式。默认为yyyy.MM.dd格式，且应该与Java 时间兼容。
time_zone ：用来设置时区。默认为UTC。

日期数学表达式解析是独立于区域设置的。因此，除了公历外，不可使用任何其他形式的日历。

必须将日期数学格式索引名称表达式括在尖括号内，并且所有特殊字符都应进行URI编码。

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

日期数学字符的百分比编码如表：

符号	编码
<	%3C
>	%3E
/	%2F
{	%7B
}	%7D

+	%2B
:	%3A
,	%2C

下表显示了日期数学索引名称的不同形式和解析后的最终索引名称，是在当前时间为2024年3月22日中午，时区为UTC的情况下解析的。

日期数字所以模式	解析结果
<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}}>

要在索引名称模板的静态部分中使用字符{和}，请使用反斜杠\对它们进行转义，例如:

    <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
    
    GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
    {
      "query" : {
        "match": {
          "test": "data"
        }
      }
    }

3、格式化所搜结果

当任何请求URL加pretty=true参数时，返回的JSON都将是格式化的(仅用于调试)。

另一个选项是设置format=yaml，结果以更可读的yaml格式返回。

4、可读输出

统计数据以适合人 ( 例如 “exists_time” : “1h” 或 “size”:“1KB”)和计算机(例如“exists_time_in_millis”: 3600000或“size_in_bytes”:1024)的格式返回。

可以通过添加 human=false来关闭对人友好可读输出格式。当统计结果被监控工具使用，而不是用于人阅读时，这是有意义的。此标志的默认值为 false。

5、格式化日期值

大多数参数都可以接受格式化日期值，例如范围查询中的gt和 lt，或范围内聚合中的from和to。

表达式以基准日期开始，可以是now，也可以是以‖结束的日期字符串。基准日期后面可以有一个或多个日期数学表达式:

+1h:加一个小时
-1d:减一天
/d:近似到天

支持的时间单位如表:

时间单位	含义
y	years
M	Months
w	Weeks
d	Days
h	Hours
H	Hours
m	Minutes
s	Seconds

假设now是2001-01-01 12:00:00，下表展示了具体的解析实例：

时间表达式	解析结果
now+1h	now加一小时，解析为：2001-01-0113:00:00
now-1h	now减一小时，解析为：2001-01-0111:00:00
now-1h/d	now减一小时并近似取值UTC00:00.解析为：2001-01-0100:00:00
2001.02.01

6、返回信息过滤

所有REST API都接受一个filter_path参数，该参数可用于减少 Elasticsearch返回的响应信息。此参数采用逗号分隔的列表形式，如下示例:

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

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

它还支持*通配符来匹配字段:

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

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

并且**通配符可以用于包含字段，而不需要知道字段的确切路径。例如，可以用这个请求返回每个段的Lucene版本:

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

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

也可以通过使用字符-前缀来排除一个或多个字段:

    GET /_count?filter_path=-_shards

    {
      "count" : 5
    }

为了获得更多的控制，可以在同一表达式中组合包含和排除过滤器。在这种情况下，将首先应用排除过滤器，并使用包含过滤器再次过滤结果:

    GET /_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 参数组合。如下示例，先索引一部分测试数据，再执行GE查询:

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

说明:一般情况下，filter_path用来过滤不必要的元数据， _source用于过滤返回的字段，类似SELECT功能。

7、展开设置

flat_settings标志会影响设置信息列表(_settings)的呈现。如果flat_settings标志为true，则以平铺格式返回设置:

    GET 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，会以更适合人可读的结构化格式返回:

    GET twitter/_settings?flat_settings=false

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

8、布尔值

所有REST API参数(请求参数和JSON主体)都支持布尔值 false和true，所有其他值都将引发错误。

9、数字值

所有REST API都支持以字符串的形式提供数字参数。

10、时间单位

每当需要指定时间区间，例如对于超时参数时，时间区间必须指定单位，如表示2天的2d。

时间单位	含义
d	Days
h	Hours
m	Minutes
s	Seconds
ms	Millisconds
miicros	Microseconds
nanos	Nanoseconds

11、数据单位

每当需要指定数据的字节大小，例如设置缓冲区大小参数时，该值必须指定单位，如10KB表示10千字节。请注意，这些单元使用 1024的幂，所以1KB表示1024字节。

数据单位	含义
b	Bytes
bk	Kilobyets
mb	Megabytes
gb	Gigabytes
tb	Terabytes
pb	Petabytes

12、缩略处理

无单位意味着它们没有“单位”，如“bytes”“Hertz” “mete”或“long tonne”。

如果这些数量中有一个很大，会把它特殊地缩略处理， 10000000打印成10m，7000打印成7k。但当我们说87的时候，我们还是会打印87。

简写	含义
k	Kilo
m	Mega
g	Giga
t	Tera
p	Peta

13、距离单位

需要指定距离(如地理距离查询中的距离参数)时，如果未指定，则默认单位为m。距离可以用其他单位指定，例如1km或 2mi(2英里)。

距离单位	含义
Mile	miormiles
Yard	ydoryards
Feet	ftorfeet
Inch	inorinch
Kilometer	kmorkilometers
Meter	mormeters
Centimeter	cmorcentimeters
Millimeter	mmormillimeters
Nauticalmile	NMornmiornauticalmiles

14、模糊性

一些查询和API支持使用模糊参数(fuzziness)进行不精确的模糊匹配。

在查询text或keyword字段时，fuzziness被解释为编辑距离，也就是一个字符串需要更改的字符数，以使其与另一个字符串相同。

fuzziness参数可以指定为如下两种值：

0，1，2：允许的最大编辑距离(或编辑次数)。
AUTO：根据Term的长度生成编辑距离。可以选择自动提供低距离和高距离参数:AUTO:[low],[high]。如果未指定，默认值为3 和6，相当于AUTO:3,6，表示长度如下所示：
- 0…2必须精确匹配
- 3…5编辑距离1
- 5编辑距离2
- AUTO一般应为fuzziness的首选值

15、启用堆栈跟踪

默认情况下，当请求返回错误时，Elasticsearch不包括错误的堆栈跟踪。可以通过将error_trace参数设置为true来启用堆栈跟踪。例如，默认情况下，将无效的size参数发送到_search API时:

    POST /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:

    POST /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
    }

16、查询字符串中的请求正文

对于不接受非POST请求的请求主体的库，可以将请求主体作为 source查询字符串参数传递。使用此方法时，还应使用指示源格式的媒体类型值 ( 如 application/json ) 传递 source_content_type 参数。

17、Content-Type要求

在请求正文中发送的内容的类型必须使用Content-Type头指定。此头的值必须映射到API支持的格式之一。大多数API支持 JSON、Yaml、Cbor等常用格式。批量和多搜索API支持Ndjson、 JSON和smile，其他类型将导致错误。

此外，使用source参数时，必须使用source_content_type参数指定内容类型。

18、基于URL的访问控制

许多用户使用具有基于URL的访问控制的代理来安全地访问 Elasticsearch索引。对于multi-search、multi-get和bulk请求，用户可以选择在URL以及请求主体中的每个请求上指定索引。这会使基于URL的访问控制变得具有挑战性。

要防止用户覆盖URL中指定的索引，请将此设置添加到 elasticsearch.yml文件中:

    rest.action.multi.allow_explicit_index: false

默认值为true，但当设置为false时，Elasticsearch将拒绝请求主体中指定了显式索引的请求。

阅读全文