API约定

最新推荐文章于 2022-08-10 10:20:01 发布

limboys

最新推荐文章于 2022-08-10 10:20:01 发布

阅读量231

点赞数

分类专栏： elasticsearch 文章标签： API约定

elasticsearch 专栏收录该内容

27 篇文章 0 订阅

订阅专栏

API约定

Multiple Indices

大多数引用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、*或没有指定索引时，此设置也适用。此设置也适用于别名，以防别名指向封闭索引。

expand_wildcards

控制通配符索引表达式可以扩展为何种具体索引。如果指定了open，则通配符表达式将扩展为仅打开索引。如果指定了closed，则通配符表达式仅扩展到封闭索引。还可以指定这两个值(open和closed)扩展到所有索引。

如果没有指定通配符，则将禁用通配符展开。如果全部指定，通配符表达式将扩展到所有索引(这相当于指定open、closed)。

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

注意:单索引api(如文档api和单索引别名api)不支持多个索引。

索引支持的数学日期格式

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

几乎所有具有索引参数的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 math索引名称表达式括在尖括号内，并且所有特殊字符都应该是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

下面的示例显示了不同形式的日期数学索引名，它们根据当前时间解析的最终索引名是utc时间2024年3月22日中午。

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

常用选项

Pretty Result

当附加?pretty=true到任何请求时，返回的JSON将被格式化（仅用于调试！）。另一种选择是设置?format=yaml哪个将导致以（有时）更可读的yaml格式返回结果。

人类可读格式输出

统计数据以适合人类查看（例如"exists_time": "1h"或"size": "1kb"）或计算机计算（例如"exists_time_in_millis": 3600000或"size_in_bytes": 1024）的格式返回。可以通过添加?human=false 查询字符串来关闭人类可读取的值。当统计结果被监控工具所应用时，这是有意义的。human标志的默认值是 false。

日期格式

表达式开始于一锚定日期,可以是”now”,或者一个以”||”为结束符的字符日期。表达式后可以跟一个或多个表达式

+1h: 加一小时

-1d: 减去一天

/d: 最近的一天

支持的单位

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

假设现在是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-01以毫秒加一个月 2001-03-01 00:00:00

相应过滤

所有REST API都接受一个filter_path参数，该参数可用于减少Elasticsearch返回的响应。此参数采用逗号进行分隔如:

GET /_search?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score

response:

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

response:

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

也可以通过在过滤器前面加上char来排除一个或多个字段-：

GET /_count?filter_path=-_shards

response:

{
  "count" : 5
}

还以将包含和排他过滤器组合在同一表达式中

GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

response:

{
  "metadata" : {
    "indices" : {
      "index-1" : {"state" : "open"},
      "index-2" : {"state" : "open"},
      "index-3" : {"state" : "open"}
    }
  }
}

Elasticsearch会直接返回字段的原始值，如_source字段。如果要筛选_source字段，则可以使用_source参数与以下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

response;

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

Response:

{

  "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，设置以更易读的结构化格式返回, 默认flat_settings设置为false
Parameters

Rest parameters(当使用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

每当需要指定数据的字节大小时，例如，在设置缓冲区大小参数时，该值必须指定单元，比如10kb对应10kb。注意，这些单位使用1024的幂，因此1kb意味着1024字节。所支持的单元包括

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

Unit-less quantities

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

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

k	公斤
m	兆
g	千兆
t	万亿
p	地图

Fuzziness

无论何处需要指定距离，例如地理距离中的distance参数，如果没有指定，则默认单位为米。距离可以用其他单位指定，例如或（2英里）。"1km""2mi"

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

启用堆栈跟踪

默认情况下，当请求返回错误时，Elasticsearch不包含错误的堆栈跟踪。您可以通过将error_traceurl参数设置为来启用该行为 true。例如，默认情况下，当您向API 发送无效size参数时_search：

POST / twitter / _search？size = surprise_me

response:

{

  "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

{

  "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

}

基于url的访问控制

许多用户使用具有基于URL的访问控制的代理来保护对Elasticsearch索引的访问。对于多搜索，多重获取和批量请求，用户可以选择在URL和请求正文中的每个单独请求中指定索引。这可以使基于URL的访问控制具有挑战性。

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

rest.action.multi.allow_explicit_index：false

默认值为true，但设置false为时，Elasticsearch将拒绝在请求正文中指定了显式索引的请求