Elasticsearch7.1中文文档-第四章-API约定

Elasticsearch REST APIs是用HTTP暴露的，而且是基于JSON的。

除非另有说明，不然本章中的约定均可以使用REST API来使用。

• 多索引
• 索引名称中支持日期数学
• 公用选项
• 基于URL的访问控制

多索引

大多数引用index参数的api支持跨多个索引执行，使用简单的test1，test2，test3表示法（或_all表示全部索引）。

全部多索引API都支持下面的url查询字符串参数：

ignore_unavailable	若是指定索引是不可用的，控制是否忽略该索引。包括b不存在的索引和已关闭(closed)的索引，能够指定ture或者false
allow_no_indices	通配符索引表达式没有具体的索引时，控制结果是否失败。能够指定true或false。例如，若是指定通配符表达式foo*，而且没有以foo开头的索引可用，请求将失败。当_all、*或没有指定索引时，此设置也适用。此设置也适用于别名，以防别名指向已关闭（closed）索引。
expand_wildcards	控制通配符索引表达式能够扩展为什么种具体索引。若是指定了open，则通配符表达式将扩展为仅打开索引。若是指定了closed，则通配符表达式仅扩展到封闭索引。还能够指定这两个值(open和closed)扩展到全部索引。

上述参数的默认设置取决于所使用的API。

与多索引API相对的是单索引API，例如DocumentAPI和aliasAPI就不支持多索引。

索引名称中支持日期数学

日期数学索引名称解析可让你搜索一段time-series区间的索引，而不是搜索全部time-series索引并过滤结果或维护别名。限制搜索索引的数量能够减小集群上的负载并提升执行性能。例如，若是在平常日志中搜索错误，可使用date math name模板将搜索限制在过去两天。

几乎全部具备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

注意在date_format中使用小写字母vs大写字母。例如:mm表示每小时的分钟，而mm表示一年的月份。一样，hh表示1-12小时范围内的小时与AM/PM相结合，而hh表示0-23 24小时范围内的小时。

注意date_format中小写和大写字母的使用。 例如：mm表示分钟，而MM表示一年中的月份。 相似地，hh表示1-12范围内的小时与AM / PM的组合，而HH表示0-23小时范围内的小时。

日期数学表达式与区域时间无关。 所以，除了公历以外，不可能使用任何其余日历。

必须将date math索引名称表达式括在大括号内，而且全部特殊字符都应该是URI编码的。例如:

# GET /<logstash-{now/d}>/_search
curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
'
复制代码

date math 字符对应的编码

日期的括号，必须使用URI编码，可参照下表：

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

下面的示例显示了不一样形式的日期数学索引名，它们根据当前时间解析的最终索引名是22nd March 2024 noon utc。

Expression	Resolves to
<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
curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}
'
复制代码

公用选项

下面全部的选项能够用在全部的API上。

美化的结果

当对请求添加pretty = true时，返回的JSON将被格式化（仅用于调试！）。 另外一种选择是设置format = yaml，这将致使以可读的yaml格式返回结果。

可读的输出

统计以可读的格式（例如“exists_time”：“1h”或“size”：“1kb”）和计算机（例如“exists_time_in_millis”：3600000或“size_in_bytes”：1024）返回。 能够经过向查询字符串添加human = false来关闭可读取的格式。 当统计结果被监视工具使用而不是供人使用时。默认值为false。

日期数学（Date Math）

大多数参数接受一个格式化的日期值，例如在range查询的gt和lt，或者daterange聚合中的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 以毫秒为单位减去1小时, 四舍五入到UTC 00:00.结果为: 2001-01-01 00:00:00
2001.02.01\|\|+1M/d	2001-02-01 以毫秒为单位加一个月. 结果为: 2001-03-01 00:00:00

响应过滤

全部的REST API均可以接受filter_path参数，能够用来减小响应的返回，此参数采用逗号分隔的过滤器列表，用点表示法表示：

curl -X GET "localhost:9200/_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版本：

curl -X GET "localhost:9200/_cluster/state?filter_path=routing_table.indices.**.state"
复制代码

响应结果：

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

复制代码

也能够经过在过滤器前面添加-来排除一个或多个字段

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参数与filter_path参数组合起来，以下所示:

curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #1", "rating": 200.1}
'
curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #2", "rating": 1.7}
'
curl -X POST "localhost:9200/library/book?refresh" -H 'Content-Type: application/json' -d'
{"title": "Book #3", "rating": 0.1}
'
curl -X GET "localhost:9200/_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设置

flat_settings标志会影响设置列表的呈现。 当flat_settings标志为true时，将以以下格式返回设置：

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

参数

REST参数（使用HTTP时，映射到HTTP URL参数）遵循使用下划线框的约定。

布尔值

全部的REST API参数（请求参数和JSON主体）都支持提供布尔值“false”做为值false，布尔值“true”做为值true。 全部其余值都会引起错误。

数值

全部REST api都支持以字符串的形式提供参数（这个字符串必须符合数字格式，例如不能是12a）。

时间单位

当须要指定持续时间时，例如对于超时参数，持续时间必须指定单位，好比2d，持续2天。支持单位包括:

d	天
h	时
m	分
s	秒
ms	毫秒
micros	微秒
nanos	纳秒

字节大小单位

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

b	Bytes
kb	Kilobytes
mb	Megabytes
gb	Gigabytes
tb	Terabytes
pb	Petabytes

无单位数量

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

若是这些量中有一个很大，咱们将打印出来，好比10m(10,000,000)或7k(7000)。当咱们的意思是87时，咱们仍然会打印87。这些是支持的乘数:

k	Kilo
m	Mega
g	Giga
t	Tera
p	Peta

距离单位

在须要指定距离的地方，好比地理距离查询中的距离参数，若是没有指定距离，默认单位是米。距离能够用其余单位表示，如“1km”或“2mi”(2英里)。

Mile	mi or 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（纳米）

模糊

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

当查询text或keyword字段时，模糊性被解释为Levenshtein编辑距离——须要对一个字符串进行的字符数更改，以使其与另外一个字符串相同。

fuzziness能够被指定为：

0, 1, 2	最大容许的 Levenshtein Edit Distance (或者编辑数)
AUTO	根据术语的长度生成编辑距离。 可选择提供低距离和高距离参数AUTO:[low],[high]。 若是未指定，则默认值为3和6，至关于AUTO:3,6表示长度： 0..2 必须彻底匹配 3..5 容许一次编辑 >5 容许两次编辑 AUTO一般应该是模糊的首选值。

启用堆栈跟踪

当请求时返回一个错误，默认状况下，Elasticsearch不会包含错误的堆栈跟踪。你能够经过设置error_traceurl参数为truel来启用堆栈跟踪，例如：默认的，当你发送一个无效的size给_searchAPI:

curl -X POST "localhost:9200/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

curl -X POST "localhost:9200/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查询字符串参数传递。当使用此方法时，source_content_type参数还应该与指示源格式的媒体类型一块儿传递，例如application/json。

Content-Type要求

必须使用Content-Type请求头指定请求体中发送的内容类型。Content-type的值必须是API支持格式之一。大多数api支持JSON、YAML、CBOR和SMILE。批量和多搜索api支持NDJSON、JSON和SMILE;其余类型将致使错误响应。

或者，当咱们使用source查询字符串参数，必须使用source_content_type指定Content-Type。

基于URL的访问控制

许多用户使用基于url的访问控制代理来确保对Elasticsearch索引的访问。对于多搜索、多获取和批量请求，用户能够选择在URL中指定索引，也能够选择在请求体中指定每一个请求的索引。

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

rest.action.multi.allow_explicit_index: false

复制代码

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