elasticsearch6.7 04.API规范

Posted wtc1994

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了elasticsearch6.7 04.API规范相关的知识,希望对你有一定的参考价值。

API Conventions

elasticsearch的REST的API是使用HTTP的JSON格式暴露的。

除非另有说明,本章中列出的约定可以在整个REST API中应用。

多索引

大多数引用index参数的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,或 no index 时,此设置也适用。如果别名指向封闭索引,则此设置也适用于别名。

expand_wildcards

? 控制通配符索引表达式可以扩展到的具体索引类型。如果指定了open,则通配符表达式将扩展为仅打开索引。如果指定closed,则通配符表达式仅扩展为闭合索引。此外,可以指定两个值(openclosed)以扩展到所有索引。

? 如果none被指定,那么通配符扩展将被禁用,如果all 被指定,通配符表达式将扩展到所有的索引(这相当于指定open,closed)。

上述参数的默认设置取决于正在使用的api。

单个索引API(如Document API单索引alias API)不支持多个索引。

索引名称支持日期格式的数学运算

日期数学索引名称解析使您能够搜索一系列时间序列索引,而不是搜索所有时间序列索引,并过滤结果或保留别名。限制搜索索引的数量可以减少集群的负载,并提高执行性能。例如,如果要在日常日志中搜索错误,则可以使用日期数学名称模板将搜索限制在过去两天。

几乎所有具有index参数的API都支持index参数值中的数学运算。

日期数学索引名称采用以下形式:

<static_name {date_math_expr {DATE_FORMAT |的time_zone}}>

说明:

参数 说明
static_name 是名称的静态文本部分
date_math_expr 是动态计算日期的动态日期数学表达式
date_format 是应该呈现计算日期的可选格式。默认为yyyy.MM.dd.格式应与java-time兼容
time_zone 是可选的时区。默认为utc

日期数学表达式与区域设置无关。因此,除了公历之外,不可能使用任何其他日历。

您必须将日期数学索引名称表达式括在尖括号内,并且所有特殊字符都应该是URI编码的。例如:

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

日期数学字符的百分比编码,用于日期舍入的特殊字符必须如下进行URI编码:

符号 URI编码
< %3C
> %3E
/ %2F
{ %7B
} %7D
| %7C
+ %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}}> logstash-2024.03.23

要使用字符{ 和 } 索引名称模板的静态部分,请使用反斜杠进行转义,例如:

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

常规选项

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

格式化相应(Pretty Result)

在任何请求后追加?pretty=true,返回的JSON格式都会非常好(仅用于调试!)。另一个选项是追加

?format=yaml,有时这将导致结果以更可读的yaml格式返回。

人类可读式输出(Human readable output)

统计数据以适合人类(例如"exists_time": “1h""size”: “1kb”)和计算机(例如"exists_time_in_millis": 3600000"size_in_bytes": 1024)的格式返回。可以通过添加“?human=false“查询字符串来关闭可读取的值。当统计结果被监测工具消耗时,这是有意义的,而不是用于人类消耗。human标志的默认值是 false。

日期数学(Date Math)

它接受一个格式化的日期值参数—比如在范围(range)查询的gt和lt,或在daterange aggregations中的from与to。

表达式以锚点日期开始,可以是now,也可以是以||结尾的日期字符串。这个锚定日期可以选择跟随一个或多个数学表达式:

  • +1h - 加一小时
  • -1d - 减去一天
  • /d - 向下舍入为最近的一天

支持的时间单位与持续时间单位支持的时间单位不同。支持的单位如下:

单位 含义
y
M
w
d
h 小时
H 小时
m 分钟
s

假设now是2001-01-01 12:00:00,一些例子是:

now+1h

? now以毫秒格式加一个小时。解析后为:2001-01-01 13:00:00

now-1h
? now以毫秒格式加一个小时。解析后为:2001-01-01 11:00:00

now-1h/d
? now以毫秒为单位舍入到UTC 00:00。解析后为:2001-01-01 00:00:00`

2001.02.01||+1M/d

? 2001.02.1以毫秒格式加一个月。解析后为:2001-03-01 00:00:00

响应过滤(Response Filtering)

所有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
      }
    ]
  }
}

它还支持通配符*来匹配任何字段或字段名称的一部分:

curl -X GET "localhost:9200/_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"}]
        }
      }
    }
  }
}

也可以通过用char前缀过滤器来排除一个或多个字段-:

curl -X GET "localhost:9200/_count?filter_path=-_shards"

响应

{
  "count" : 5
}

而对于更多的控制,包容性和排他性的过滤器可以组合在同一个表达式中。在这种情况下,首先应用排他性过滤器,并使用包含性过滤器再次过滤结果:

curl -X GET "localhost:9200/_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参数(参见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)

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

默认情况下flat_settings设置为false。

参数(Parameters)

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

布尔值(Boolean Values)

所有REST API参数(请求参数和JSON主体)都支持提供布尔值“false”作为值false,布尔值“true”作为值true。所有其他值将引发错误。

数值(Number Values)

所有REST API都支持在JSON数字类型的基础上将编号参数作为字符串提供。

时间单位(Time units)

无论何时需要指定持续时间,例如对于timeout参数,持续时间必须指定该单位,如2d代表2天。支持的单位如下:

单位 含义
d
h 小时
m 分钟
s
ms 毫秒
micros 微秒
nanos 纳秒

字节大小单位(Byte size units)

每当需要指定数据的字节大小时,例如,设置缓冲区大小参数时,该值必须指定单位,如10千字节为10千字节。请注意,这些单位使用1024的幂,因此1kb表示1024字节。支持的单位是:

单位 含义
b 字节
kb 千字节
mb 兆字节
gb 千兆字节
tb 兆兆字节
pb 拍字节

无单位量化(Unit-less quantities)

无单位数量意味着它们没有“单位”,如“字节”或“赫兹”或“米”或“长吨”。

如果这些数量中的一个很大,我们会将其打印出来,例如10万,10,000,000或7k,7,000。当我们的意思是87时,我们仍会打印87。这些是受支持的乘数:

缩写 含义
k Kilo(公斤)
m Mega(兆)
g Giga(千兆)
t Tera(万亿)
p Peta(千兆)

距离单位(Distance Units)

无论何处需要指定距离,例如地理距离查询中的距离参数,如果未指定距离,则默认单位为米。距离可以在其他单位中指定,例如“1km”或“2mi”(2英里)。

名称 单位参数
Mile(英里) mi 或 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)

一些查询和API支持使用fuzziness参数进行模糊匹配。

当查询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

启用堆栈轨迹(Enabling stack traces)

默认情况下,当请求返回错误时,Elasticsearch不包括错误的堆栈跟踪。您可以通过设置error_traceurl参数为true来启用该行为。例如,默认情况下向_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]
    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"
    at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
    }
  },
  "status": 400
}

查询字符串中的请求正文(Request body in query string)

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

必要的Content-Type

在请求体中发送的内容类型必须使用Content-Type标头来指定。此标头的值必须映射到API所支持的其中一种格式。大多数API支持JSON,YAML,CBOR和SMILE。批量和多搜索API支持NDJSON,JSON和SMILE; 其他类型将导致错误响应。

此外,使用source查询字符串参数时,必须使用source_content_type查询字符串参数指定内容类型。

基于URL的访问控制(Content-Type Requirements)

许多用户使用基于URL访问控制的代理来保护对Elasticsearch索引的访问。对于multi-search, multi-get, and bulk r请求,用户可以选择在URL中指定一个索引,也可以在请求主体中的每个请求中指定一个索引。这可以使基于URL的访问控制具有挑战性。

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

rest.action.multi.allow_explicit_index:false

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

以上是关于elasticsearch6.7 04.API规范的主要内容,如果未能解决你的问题,请参考以下文章

elasticsearch6.7 05. Document APIs

elasticsearch6.7 01.入门指南

elasticsearch6.7 01.入门指南

Docker中安装elasticsearch6.7.1

Docker中安装elasticsearch6.7.1

elasticsearch6.7 01.入门指南