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

骑猪看日落 2024-02-21 08:39 83阅读 0赞

#### 目录 ####

*  Rest API通用参数
 *   *  1、多索引
     *  2、日期数学格式
     *  3、格式化所搜结果
     *  4、可读输出
     *  5、格式化日期值
     *  6、返回信息过滤
     *  7、展开设置
     *  8、布尔值
     *  9、数字值
     *  10、时间单位
     *  11、数据单位
     *  12、缩略处理
     *  13、距离单位
     *  14、模糊性
     *  15、启用堆栈跟踪
     *  16、查询字符串中的请求正文
     *  17、Content-Type要求
     *  18、基于URL的访问控制

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

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

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

<table> 
 <thead> 
  <tr> 
   <th align="left">日期数字所以模式</th> 
   <th align="left">解析结果</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/d}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.22</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.01</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M{yyyy.MM}}&gt;</code></td> 
   <td align="left"><code> logstash-2024.03</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/M-1M{yyyy.MM}}&gt;</code></td> 
   <td align="left"><code>logstash-2024.02</code></td> 
  </tr> 
  <tr> 
   <td align="left"><code>&lt;logstash-{now/d{yyyy.MM.dd|+12:00}}&gt;</code></td> 
   <td align="left"><code>logstash-2024.03.23</code></td> 
  </tr> 
 </tbody> 
</table>

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

<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`:近似到天

支持的时间单位如表:

<table> 
 <thead> 
  <tr> 
   <th align="left">时间单位</th> 
   <th align="left">含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>y</code></td> 
   <td align="left">years</td> 
  </tr> 
  <tr> 
   <td align="left"><code>M</code></td> 
   <td align="left">Months</td> 
  </tr> 
  <tr> 
   <td align="left"><code>w</code></td> 
   <td align="left">Weeks</td> 
  </tr> 
  <tr> 
   <td align="left"><code>d</code></td> 
   <td align="left">Days</td> 
  </tr> 
  <tr> 
   <td align="left"><code>h</code></td> 
   <td align="left">Hours</td> 
  </tr> 
  <tr> 
   <td align="left"><code>H</code></td> 
   <td align="left">Hours</td> 
  </tr> 
  <tr> 
   <td align="left"><code>m</code></td> 
   <td align="left">Minutes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>s</code></td> 
   <td align="left">Seconds</td> 
  </tr> 
 </tbody> 
</table>

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

<table> 
 <thead> 
  <tr> 
   <th align="left">时间表达式</th> 
   <th align="left">解析结果</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>now+1h</code></td> 
   <td align="left">now加一小时，解析为：2001-01-01 13:00:00</td> 
  </tr> 
  <tr> 
   <td align="left"><code>now-1h</code></td> 
   <td align="left">now减一小时，解析为：2001-01-01 11:00:00</td> 
  </tr> 
  <tr> 
   <td align="left"><code>now-1h/d</code></td> 
   <td align="left">now减一小时并近似取值UTC 00:00.解析为：2001-01-01 00:00:00</td> 
  </tr> 
  <tr> 
   <td align="left"><code>2001.02.01||+1M/d</code></td> 
   <td align="left">2001-02-01减一个月，解析为：2001-03-01 00:00:00</td> 
  </tr> 
 </tbody> 
</table>

### 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。

<table> 
 <thead> 
  <tr> 
   <th align="left">时间单位</th> 
   <th align="left">含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>d</code></td> 
   <td align="left">Days</td> 
  </tr> 
  <tr> 
   <td align="left"><code>h</code></td> 
   <td align="left">Hours</td> 
  </tr> 
  <tr> 
   <td align="left"><code>m</code></td> 
   <td align="left">Minutes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>s</code></td> 
   <td align="left">Seconds</td> 
  </tr> 
  <tr> 
   <td align="left"><code>ms</code></td> 
   <td align="left">Millisconds</td> 
  </tr> 
  <tr> 
   <td align="left"><code>miicros</code></td> 
   <td align="left">Microseconds</td> 
  </tr> 
  <tr> 
   <td align="left"><code>nanos</code></td> 
   <td align="left">Nanoseconds</td> 
  </tr> 
 </tbody> 
</table>

### 11、数据单位 ###

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

<table> 
 <thead> 
  <tr> 
   <th align="left">数据单位</th> 
   <th align="left">含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>b</code></td> 
   <td align="left">Bytes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>bk</code></td> 
   <td align="left">Kilobyets</td> 
  </tr> 
  <tr> 
   <td align="left"><code>mb</code></td> 
   <td align="left">Megabytes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>gb</code></td> 
   <td align="left">Gigabytes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>tb</code></td> 
   <td align="left">Terabytes</td> 
  </tr> 
  <tr> 
   <td align="left"><code>pb</code></td> 
   <td align="left">Petabytes</td> 
  </tr> 
 </tbody> 
</table>

### 12、缩略处理 ###

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

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

### 13、距离单位 ###

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

<table> 
 <thead> 
  <tr> 
   <th align="left">距离单位</th> 
   <th align="left">含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">Mile</td> 
   <td align="left"><code>mi</code> or <code>miles</code></td> 
  </tr> 
  <tr> 
   <td align="left">Yard</td> 
   <td align="left"><code>yd</code> or <code>yards</code></td> 
  </tr> 
  <tr> 
   <td align="left">Feet</td> 
   <td align="left"><code>ft</code> or <code>feet</code></td> 
  </tr> 
  <tr> 
   <td align="left">Inch</td> 
   <td align="left"><code>in</code> or <code>inch</code></td> 
  </tr> 
  <tr> 
   <td align="left">Kilometer</td> 
   <td align="left"><code>km</code> or <code>kilometers</code></td> 
  </tr> 
  <tr> 
   <td align="left">Meter</td> 
   <td align="left"><code>m</code> or <code>meters</code></td> 
  </tr> 
  <tr> 
   <td align="left">Centimeter</td> 
   <td align="left"><code>cm</code> or <code>centimeters</code></td> 
  </tr> 
  <tr> 
   <td align="left">Millimeter</td> 
   <td align="left"><code>mm</code> or <code>millimeters</code></td> 
  </tr> 
  <tr> 
   <td align="left">Nautical mile</td> 
   <td align="left"><code>NM</code> or <code>nmi</code> or <code>nauticalmiles</code></td> 
  </tr> 
 </tbody> 
</table>

### 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将拒绝请求 主体中指定了显式索引的请求。