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 标头编辑

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

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

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

traceparent HTTP 标头编辑

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

如果提供，Elasticsearch 会在以下位置将标头的 trace-id 值显示为 trace.id：

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

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

GET 和 POST 请求编辑

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

Cron 表达式编辑

Cron 表达式是以下形式的字符串

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

Elasticsearch 使用 Quartz 作业调度程序 中的 cron 解析器。 有关编写 Quartz cron 表达式的更多信息，请参阅 Quartz CronTrigger 教程。

所有计划时间均采用协调世界时 (UTC)；不支持其他时区。

Cron 表达式元素编辑

除 year 外，所有元素均为必需的。 有关允许的特殊字符的信息，请参阅 Cron 特殊字符。

Cron 特殊字符编辑

L

最后。 在 day_of_month 字段中使用表示该月的最后一天，即 1 月的 31 日、非闰年 2 月的 28 日、4 月的 30 日，依此类推。 在 day_of_week 字段中单独使用以代替 7 或 SAT，或在特定星期几之后使用以选择该月该类型的最后一天。 例如，6L 表示该月的最后一个星期五。 您可以在 day_of_month 字段中指定 LW 以指定该月的最后一个工作日。 指定值列表或范围时，请避免使用 L 选项，因为结果可能与您的预期不符。

#

0 5 9 * * ?

在 2020 年期间，每天 UTC 时间上午 9:05 触发。

每天从 UTC 时间上午 9:00 开始到上午 9:45 结束，每 15 分钟触发一次。

索引和索引别名中的日期数学支持编辑

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

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

<static_name{date_math_expr{date_format|time_zone}}>

其中

日期数学表达式的解析与语言环境无关。因此，除了公历之外，不可能使用任何其他日历。

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

resp = client.indices.create(
    index="<my-index-{now/d}>",
)
print(resp)

response = client.indices.create(
  index: '<my-index-{now/d}>'
)
puts response

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

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

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

以下示例显示了一个搜索请求，该请求搜索过去三天内的 Logstash 索引，假设这些索引使用默认的 Logstash 索引名称格式 logstash-YYYY.MM.dd。

$params = [
    'index' => '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E',
    'body' => [
        'query' => [
            'match' => [
                'test' => 'data',
            ],
        ],
    ],
];
$response = $client->search($params);

resp = client.search(
    index=[
        "<logstash-{now/d-2d}>",
        "<logstash-{now/d-1d}>",
        "<logstash-{now/d}>",
    ],
    body={"query": {"match": {"test": "data"}}},
)
print(resp)

response = client.search(
  index: '<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>',
  body: {
    query: {
      match: {
        test: 'data'
      }
    }
  }
)
puts response

res, err := es.Search(
	es.Search.WithIndex("%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E"),
	es.Search.WithBody(strings.NewReader(`{
	  "query": {
	    "match": {
	      "test": "data"
	    }
	  }
	}`)),
	es.Search.WithPretty(),
)
fmt.Println(res, err)

const response = await client.search({
  index: '%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E',
  body: {
    query: {
      match: {
        test: 'data'
      }
    }
  }
})
console.log(response)

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

多目标语法编辑

大多数接受 <data-stream>、<index> 或 <target> 请求路径参数的 API 也支持*多目标语法*。

在多目标语法中，您可以使用逗号分隔列表对多个资源（例如数据流、索引或别名）运行请求：test1,test2,test3。您还可以使用 类似 glob 的 通配符 (*) 表达式来定位与模式匹配的资源：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。

REST API 版本兼容性编辑

主要版本升级通常包括许多重大更改，这些更改会影响您与 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

HTTP 429 Too Many Requests 状态代码推回编辑

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

基于 URL 的访问控制编辑

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

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

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

布尔值编辑

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

数值编辑

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

resp = client.search(
    body={"size": "1000"},
)
print(resp)

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

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

字节大小单位编辑

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

距离单位编辑

每当需要指定距离时（例如，地理距离 中的 distance 参数），如果未指定单位，则默认单位为米。可以使用其他单位指定距离，例如 "1km" 或 "2mi"（2 英里）。

完整的单位列表如下：

时间单位编辑

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

无单位量编辑

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

如果其中一个量很大，我们会将其打印为 10m（表示 10,000,000）或 7k（表示 7,000）。不过，如果我们指的是 87，我们仍然会打印 87。以下是支持的乘数：