【Elasticsearch7.0】之api约定

  |   0 评论   |   45 浏览

概述

es REST api通过http接口访问,他的格式为json。除非有其他的一些说明,不然这个api约定适用所有的es使用场景。

多索引

大多数引用索引参数的api都支持跨多个索引执行,使用简单的test1、test2、test3表示或者使用_all来表示所有索引。还支持通配符,如test**testte*t*test*等,还可以通过-来排除某些值,如:test*,-test3
所有多索引api都支持以下url查询字符串参数:
ignore_unavailable:控制是否忽略任何指定的索引不可用,包括不存在的索引或已关闭的索引,可以设置true或者false。

allow_no_indices:控制如果通配符索引表达式导致没有具体索引时是否失败,可以设置为true或者false,例如设置了通配符表达式foo*,但是没有foo索引,那么根据设置请求会失败。当_all、*或没有指定索引时,此设置也适用,此设置也适用于别名,以防别名指向关闭索引。

expand_wildcards:控制通配符索引表达式可以扩展为何种具体索引,如果指定了open,则通配符表达式将扩展为仅打开索引。如果指定了closed,则通配符表达式仅扩展到关闭索引,还可以指定这两个值(open,closed)扩展到所有索引。如果指定none,那么通配符扩展将不可用,如果指定all,那么通配符将扩展到所有索引(相当于指定open,closed)。

上述参数的默认设置取决于所使用的API。
注意:单索引api(如Document APIs和single-index alias APIs )不支持多个索引。

日期计算支持

日期计算索引名称解析使你能够搜索一系列时间序列索引,而不是搜索所有的时间序列索引并过滤结果或维护别名。限制搜索索引的数量可以减少集群上的负载并提高执行性能。例如,如果你正在搜索日常日志中的错误,可以使用日期计算模板来限制只查过去几天的数据。
几乎所有的api接口都支持日期计算参数。语法如下:

<static_name{date_math_expr{date_format|time_zone}}>

static_name:名称的静态文本部分。
date_math_expr:动态日期计算表达式,动态计算日期。
date_format:日期的格式,默认是yyyy.MM.dd,格式与DateTimeFormatter一致。
time_zone:可选时区,默认是utc。
注意:在date_format中大写和小写表示不同的含义,例如:mm表示小时里的分钟,而MM表示一年中的月份,hh表示12小时制,通过AP/PM来区分,HH表示24小时制。
日期计算表达式是与区域无关的解析表达式,因此,除了公历,不可能使用任何其他日历。必须将日期计算索引名称表达式括在尖括号内,并且所有特殊字符都应该是URI编码的,例如:

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

URI编码对照表如下:

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

下面给出了一些示例:

表达式	                                  解析为
<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}> 解析为 elastic{ON}-2024.03.01
下面的示例显示了一个搜索请求,它搜索过去三天的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"
    }
  }
}

通用设置

以下选项可以应用于所有REST api。

美化结果

可以在所有请求后面加入?pretty=true,就可以对输出的json进行美化(只有使用curl的时候才有效果)。如果请求后面设置了?format=yaml,那么将以yaml格式进行输出。
未设置pretty参数:
image.png
设置了pretty参数:
image.png
设置了format=yaml
image.png

返回值可读性

返回结果分两种,一种是可读性比较好,如:"exists_time": "1h"或者"size": "1kb",另一种是可读性就没那么好了,如:"exists_time_in_millis": 3600000或者"size_in_bytes": 1024。可以在请求中设置?human=false,来表示是否开启返回值可读性。human为false是当统计结果被监视工具使用而不是供人使用时,这是有意义的,默认human是false。
image.png

日期计算

大多数请求都可以接收日期格式的参数,如range query接口中的gt和lt,Date Range Aggregation接口中的from和to。
日期表达式以基准时间开始,基准时间可以是now,或者以||结果的时间,该时间后面可以跟一个或多个计算表达式:
+1h:表示加一个小时;
-1d:表示减一天;
/d:四舍五入到最近的一天;
时间缩写对应具体时间:

y 年
M 月
w 周
d 天
h 小时
H 小时
m 分钟
s 秒

假如now表示2019-01-01 12:00:00,看下面示例:
now+1h :解析为2019-01-01 13:00:00
now-1h:解析为2019-01-01 11:00:00
now-1h/d:现在的时间减一小时, 再四舍五入到UTC 00:00,解析为2019-01-01 00:00:00
2019.02.01||+1M/d:表示2019.02.01加一个月,再四舍五入到UTC 00:00,解析为2019.03.01 00:00:00

指定返回值

所有的接口都可以设置filter_path,来指定返回值,这样可以减少请求大小,多个值可以用短号隔开,示例如:

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

可以用 ** 通配符来表示包含属性,不用知道该属性所在的路径,如:

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有哪些属性,如下示例:

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影响显示结果,如果设置为true,那么结果将以扁平化的格式进行输出,默认为false。示例如:

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

如果设置为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"
      }
    }
  }
}

参数

Rest参数(当使用HTTP时,映射到HTTP URL参数)遵循使用下划线大小写的约定。

boolean值

所有REST API参数(包括请求参数和JSON主体)都支持提供boolean“false”作为值,boolean“true”作为值,其他值会报错。

Number值

所有REST api都支持在原生JSON数字类型的基础上以字符串的形式提供数字的参数。

时间单位

当需要指定持续时间时,例如对于timeout参数,持续时间必须指定单位,比如2d表示持续2天,支持的时间单位:

d 天
h 小时
m 分钟
s 描述
ms 毫秒
micros 微秒
nanos 纳秒

字节长度单位

当需要知道字节长度时,如当参数中需要指定缓冲区大小时,那么需要指定该值,比如10kb表示10*1024字节,注意,这些单位使用1024的幂,所以1kb表示1024字节,支持以下单位:

b 字节
kb 千字节
mb 兆字节
gb 千兆字节
tb 兆兆字节
pb 千兆字节

计量单位

计量单位意味着它们没有“单位”,如"bytes" or “Hertz” or “meter” or “long tonne”。如果这些量中有一个很大,我们将打印出来,比如10m(1000万美元)或7k(7000美元),当我们的意思是87时,我们仍然会打印87,支持的计量单位:

k 千克
m 兆
g 吉(咖)
t 太(拉)
p 拍(它)

距离单位

像距离单位需要指定的时候,如Geo Distance Query接口中可以指定distance参数,如果没有指定米,则默认单位是米,距离可以用其他单位表示,如“1km”或“2mi”(2英里)。支持的距离单位:

mi或者miles 英里 
yd或者yards  码 
ft或者feet 英尺 
in或者inch 英寸 
km或者kilometers 千米 
m或者meters 公尺 
cm或者centimeters 厘米 
mm或者millimeters 毫米 
NM, nmi或者nauticalmiles 海里

模糊度参数

一些查询和api支持使用模糊参数进行不精确的模糊匹配。当查询text或者keyword属性时,fuzziness被解释为Levenshtein编辑距离(需要对一个字符串进行的字符数更改,以使其与另一个字符串相同。)
fuzziness参数可以指定为:

0,1,2  允许的最大Levenshtein编辑距离(或编辑次数)
AUTO  根据项的长度生成编辑距离,低距离和高距离参数可以选择使用AUTO:[low],[high]。如果没有指定,默认值是3和6,相当于AUTO:3,6,表示长度:0..2表示必须完全匹配;3..5表示一个编辑允许;>5表示两个编辑允许;

通常情况下fuzziness优先选择AUTO参数。

启动堆栈信息

默认情况下,请求是不显示错误堆栈信息的,可以在请求里面设置error_trace为true,例如:对_search请求的size传一个非法的值,没有设置error_trace的情况

GET /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的情况:

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

查询方法请求体

对于不接受非post请求的请求体的库,可以将请求体作为源查询字符串参数传递。当使用此方法时,source_content_type参数还应该与指示源格式的媒体类型值一起传递,例如application/json。

content-type要求

在请求体中发送的内容的类型必须使用content-type头指定,此头的值必须映射到API支持的格式之一,大多数api支持JSON、YAML、CBOR和SMILE。批量和多搜索api支持NDJSON、JSON和SMILE;其他类型将导致错误响应。此外,在使用源查询字符串参数时,必须使用source_content_type查询字符串参数指定内容类型。

基于url的访问控制

许多用户使用基于url的访问控制代理来确保对Elasticsearch索引的访问。对于multi-search, multi-get和bulk请求,用户可以选择在URL中指定索引,也可以选择在请求体中指定每个请求的索引。这使得基于url的访问控制具有挑战性。要防止用户覆盖URL中指定的索引,请将此设置添加到elasticsearch.yml文件

rest.action.multi.allow_explicit_index: false

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

也可以关注我的公众号:程序之声
图片
关注公众号,领取更多资源

本文为博主原创文章,未经博主允许不得转载。

评论

发表评论