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 兼容性仅在一个主要版本之间得到尊重：尊重 7.x 的请求/响应从 8.x 开始。

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

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

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兼容性。

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

在从7.17升级到9.0.0-beta1期间利用REST API兼容性：