API 约定

Elasticsearch REST API 通过 HTTP 暴露。 除非另有说明，以下约定适用于所有 API。

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

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

Elasticsearch 仅支持 UTF-8 编码的 JSON。Elasticsearch 会忽略任何随请求发送的其他编码头。响应也是 UTF-8 编码的。

您可以传递一个 X-Opaque-Id HTTP 头来跟踪请求在 Elasticsearch 日志和任务中的来源。如果提供了该头，Elasticsearch 会在以下位置显示 X-Opaque-Id 的值：

对于弃用日志，Elasticsearch 还使用 X-Opaque-Id 值来限制和去重弃用警告。请参阅 弃用日志限制。

The X-Opaque-Id header 接受任何任意值。然而，我们建议您将这些值限制在一个有限的集合内，例如每个客户端一个ID。不要为每个请求生成唯一的 X-Opaque-Id header。太多的唯一 X-Opaque-Id 值可能会阻止 Elasticsearch 在弃用日志中去除重复的警告。

Elasticsearch 还支持使用 官方 W3C 跟踪上下文规范的 traceparent HTTP 头。您可以使用 traceparent 头来跟踪跨 Elastic 产品和其它服务的请求。因为它仅用于跟踪，您可以安全地为每个请求生成唯一的 traceparent 头。

如果提供，Elasticsearch 会将头部的 trace-id 值作为 trace.id 显示在：

例如，以下 traceparent 值将生成上述日志中的以下 trace.id 值。

`traceparent`: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
`trace.id`: 0af7651916cd43dd8448eb211c80319c

许多Elasticsearch GET API（特别是搜索API）支持请求体。 虽然GET操作在检索信息方面是有意义的， 但并非所有HTTP库都支持带有请求体的GET请求。 所有需要请求体的Elasticsearch GET API也可以作为POST请求提交。 或者，您可以在使用GET时将请求体作为 source查询字符串参数传递。

cron 表达式是一个以下列形式组成的字符串：

    <seconds> <minutes> <hours> <day_of_month> <month> <day_of_week> [year]

Elasticsearch 使用来自 Quartz Job Scheduler 的 cron 解析器。 有关编写 Quartz cron 表达式的更多信息，请参阅 Quartz CronTrigger 教程。

所有计划时间均为协调世界时（UTC）；不支持其他时区。

所有元素都是必需的，除了year。 有关允许的特殊字符的信息，请参见Cron特殊字符。

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

大多数接受索引或索引别名参数的API都支持日期数学。日期数学名称采用以下形式：

<static_name{date_math_expr{date_format|time_zone}}>

其中：

日期数学表达式是独立于本地化进行解析的。因此，不可能使用除公历以外的其他日历。

您必须将日期数学名称括在尖括号中。如果在请求路径中使用该名称，特殊字符必须进行URI编码。例如：

# PUT /<my-index-{now/d}>
PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E

以下示例展示了不同形式的日期数学名称及其在当前时间为2024年3月22日中午UTC时解析为的最终名称。

要在名称模板的静态部分中使用字符 { 和 }，请使用反斜杠 \ 进行转义，例如：

以下示例展示了一个搜索请求，该请求搜索过去三天的 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"
    }
  }
}

大多数接受 、 或 请求路径参数的 API 也支持 多目标语法。

在多目标语法中，您可以使用逗号分隔的列表来对多个资源（如数据流、索引或别名）运行请求： test1,test2,test3。您还可以使用类似全局 通配符（*）表达式来定位与模式匹配的资源：test* 或 *test 或 te*t 或 *test*。

您可以使用-字符排除目标：test*,-test3。

您还可以使用-字符从要搜索的集群列表中排除集群： remote*:*,-remote1:*,-remote4:*将搜索所有别名以"remote"开头的集群，但不包括"remote1"和"remote4"。请注意，使用此表示法排除集群时，必须排除其所有索引。目前不支持排除远程集群的子集索引。例如，这将抛出异常： remote*:*,-remote1:logs*。

支持多目标的API可以支持以下查询字符串参数：

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

一些可以针对索引的多目标API还支持以下查询字符串参数：

对于大多数API，通配符表达式默认不匹配隐藏的数据流和索引。要使用通配符表达式匹配隐藏的数据流和索引，您必须指定expand_wildcards查询参数。

或者，查询以点开头的索引模式，例如 .watcher_hist*，将默认匹配隐藏索引。这是为了 镜像Unix文件通配行为，并提供更平滑的过渡路径到 隐藏索引。

您可以通过在流的匹配索引模板中将data_stream.hidden设置为true来创建隐藏的数据流。您可以使用index.hidden索引设置来隐藏索引。

数据流的备份索引是自动隐藏的。一些功能，例如机器学习，会将信息存储在隐藏的索引中。

匹配所有索引的全局索引模板不会应用于隐藏索引。

Elasticsearch 模块和插件可以将配置和状态信息存储在内部的 系统索引 中。 您不应直接访问或修改系统索引， 因为它们包含对系统运行至关重要的数据。

Rest 参数（当使用 HTTP 时，映射到 HTTP URL 参数）遵循使用下划线命名法的惯例。

对于不接受非POST请求的请求体的库， 您可以将请求体作为source查询字符串参数传递。 使用此方法时，还应传递source_content_type参数， 并附带一个指示源格式（如application/json）的媒体类型值。

主要版本升级通常包括许多会影响您与Elasticsearch交互方式的重大更改。 尽管我们建议您在升级Elasticsearch之前监控弃用日志并更新应用程序， 但协调必要的更改可能会成为升级的障碍。

您可以通过包含API兼容性头文件来启用现有应用程序在升级后无需修改即可运行，这些头文件告诉Elasticsearch您仍在使用先前版本的REST API。使用这些头文件可以使请求和响应的结构保持不变；但这并不保证行为相同。

您可以在每个请求的基础上，通过Content-Type和Accept头设置版本兼容性。 将compatible-with设置为您正在运行的版本的主要版本号不会产生影响， 但可以确保在Elasticsearch升级后请求仍然有效。

要告知 Elasticsearch 8.0 您正在使用 7.x 的请求和响应格式，请设置 compatible-with=7：

Content-Type: application/vnd.elasticsearch+json; compatible-with=7
Accept: application/vnd.elasticsearch+json; compatible-with=7

Elasticsearch API 可能会返回 HTTP 429 Too Many Requests 状态码，表示集群过于繁忙，无法处理请求。当发生这种情况时，请考虑在短暂延迟后重试。如果重试也收到 429 Too Many Requests 响应，请在每次后续重试前通过指数退避延长延迟时间。

许多用户使用基于URL的访问控制代理来保护对Elasticsearch数据流和索引的访问。对于多搜索、多获取和批量请求，用户可以选择在URL中指定数据流或索引，并在请求体中的每个单独请求中指定。这可能会使基于URL的访问控制变得具有挑战性。

为了防止用户覆盖URL中指定的数据流或索引，请在elasticsearch.yml中将rest.action.multi.allow_explicit_index设置为false。

这会导致 Elasticsearch 拒绝在请求体中显式指定数据流或索引的请求。

所有REST API参数（包括请求参数和JSON体）都支持将布尔值“false”作为值false，将布尔值“true”作为值true。所有其他值都将引发错误。

在请求体中传递数值参数时，您可以使用包含数字的字符串，而不是原生的数值类型。例如：

POST /_search
{
  "size": "1000"
}

响应体中的整数值字段在本手册中描述为 integer（或偶尔为 long），但通常对这些值没有明确的界限。JSON、SMILE、CBOR 和 YAML 都允许任意大的整数值。不要假设响应体中的 integer 字段总是适合 32 位有符号整数。

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

无论何时需要指定距离，例如在Geo-distance中的distance参数，如果未指定单位，默认单位为米。距离可以以其他单位指定，例如"1km"或"2mi"（2英里）。

完整的单位列表如下：

每当需要指定持续时间时，例如对于一个timeout参数，持续时间必须指定单位，如2d表示2天。支持的单位有：

无量纲量意味着它们没有像“字节”或“赫兹”或“米”或“长吨”这样的“单位”。

如果这些数量中的一个是大的，我们会像10m表示10,000,000或7k表示7,000那样打印出来。不过，当我们表示87时，我们仍然会打印87。这些是支持的乘数：