REST API 兼容性

为了帮助 REST 客户端减轻不兼容（破坏性）API 更改的影响，Elasticsearch 提供了每个请求的可选择 API 兼容模式。

Elasticsearch REST API 在不同版本之间通常是稳定的。但是，某些改进需要进行与先前版本不兼容的更改。例如，Elasticsearch 7.x 在许多 URL 路径中支持自定义映射类型，但 Elasticsearch 8.0+ 不支持（请参阅 删除映射类型）。在发送到 Elasticsearch 8.0+ 的请求中指定自定义类型将返回错误。但是，如果您请求 REST API 兼容性，即使不再支持映射类型，Elasticsearch 也会接受该请求。

当某个 API 计划被删除或将以不兼容的方式更改时，原始 API 将在一个或多个版本中被弃用。使用原始 API 会在日志中触发弃用警告。这使您可以在升级之前查看弃用日志并采取适当的措施。但是，在某些情况下，很难识别所有使用已弃用 API 的位置。这就是 REST API 兼容性可以提供帮助的地方。

当您请求 REST API 兼容性时，Elasticsearch 会尝试遵守先前的 REST API 版本。Elasticsearch 会尝试应用最兼容的 URL、请求体、响应体和 HTTP 参数。

对于兼容的 API，这没有任何影响——它只会影响对与先前版本有破坏性更改的 API 的调用。如果 Elasticsearch 无法自动解决不兼容问题，则仍然可以在兼容模式下返回错误。

REST API 兼容性应该是平稳升级过程的桥梁，而不是长期策略。REST API 兼容性仅在主要版本之间有效：支持来自 8.x 的 7.x 请求/响应。

当您使用 REST API 兼容性提交请求并且 Elasticsearch 解决了不兼容问题时，将向弃用日志写入一条消息，类别为“compatible_api”。查看弃用日志以识别使用中的任何差距和完全支持的功能。

有关特定重大更改以及请求兼容模式的影响的信息，请参阅迁移指南中的REST API 更改。

REST API 兼容性通过 Accept 和/或 Content-Type 标头按请求实现。

例如

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

始终需要 Accept 标头，并且仅当请求随请求一起发送正文时才需要 Content-Type 标头。与 7.x 或 8.x Elasticsearch 服务器通信时，以下值有效

"application/vnd.elasticsearch+json;compatible-with=7"
"application/vnd.elasticsearch+yaml;compatible-with=7"
"application/vnd.elasticsearch+smile;compatible-with=7"
"application/vnd.elasticsearch+cbor;compatible-with=7"

官方支持的 Elasticsearch 客户端可以为所有请求启用 REST API 兼容性。

要为 Elasticsearch 接收的所有请求启用 REST API 兼容性，请将环境变量 ELASTIC_CLIENT_APIVERSIONING 设置为 true。

在从 7.17 升级到 8.17.0 期间利用 REST API 兼容性