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 的调用，这些 API 与先前版本存在重大更改。如果 Elasticsearch 无法自动解决不兼容性，则即使在兼容性模式下也可能返回错误。

REST API 兼容性应该是一座桥梁，以平滑升级过程，而不是长期策略。REST API 兼容性仅在一个主要版本之间有效：从 8.x 接受 7.x 请求/响应。

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

有关特定重大更改以及请求兼容性模式的影响的信息，请参阅迁移指南中的 REST 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。

REST API 兼容性工作流程编辑

要利用 REST API 兼容性在从 7.17 升级到 8.14.2 期间，请执行以下操作：