【Elasticsearch7.0】之api约定

star2017 1年前 ⋅ 581 阅读

概述

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

多索引

大多数引用索引参数的api都支持跨多个索引执行，使用简单的test1、test2、test3表示或者使用_all来表示所有索引。还支持通配符，如test*、*test、te*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将拒绝在请求体中指定显式索引的请求。

本文为博主原创文章，未经博主允许不得转载。
更多内容请访问：IT源点

注意：本文归作者所有，未经作者允许，不得转载

#全文搜索
阅读全部
相关文章推荐
  • 1
  • 2

全部评论: 0 条

    我有话说: