Python 中 Elasticsearch 8 的重要语法更新

帮助您应对 Elasticsearch 的重大变化的一些技巧

Elasticsearch Python 客户端库的版本 8 中有不少重大更改，当您将库从版本 7 更新到 8 时会给您带来很多麻烦。尽管这可能是一项痛苦的任务，但仍然建议您将库更新到最新版本，因为添加了许多新功能并且应该更加用户友好。在这篇文章中，我们将概述 Elasticsearch 8 的重要语法更新，这将有助于您重构代码以使其与最新版本的库一起使用。

Preparations

如果您想测试本文中演示的代码片段，最好让 Elasticsearch 服务器在本地运行。我们将使用 Docker 使用最新版本的 Docker 镜像启动 Elasticsearch 和 Kibana 容器，在撰写本文时这些镜像是 8.2.2 版本，但也应该适用于版本 8 的其他镜像。[0]

此外，我们需要安装 Elasticsearch Python 客户端库的版本 8。最好将它安装在虚拟环境中，这样它就不会影响系统上现有的库。[0]

使用严格的客户端配置进行连接

在 Elasticsearch 版本 8 中，scheme、host 和 port 的默认值被移除，我们现在需要明确指定它们。否则会出现ValueError：

有关客户端配置的更多示例，请查看此 GitHub 问题。[0]

使用 Elasticsearch 而不是 IndicesClient 来管理索引

我们曾经使用 IndicesClient 类来管理索引。但是，它已被弃用，我们现在应该使用 Elasticsearch 类来直接管理索引。实际上，在这篇文章中，我们将使用上面创建的 es_client 对象来执行所有与索引相关的操作。[0]

API 只允许使用关键字参数

在 Elasticsearch 版本 8 中，我们只能对所有 API 使用关键字参数。现在使用关键字参数将引发 TypeError：

使用 client.options() 指定传输参数

现在应该使用 client.options() 指定每个请求的选项（如忽略），而不是在 API 方法中。此外，ignore 现在重命名为 ignore_status。

可以在此处找到使用 client.options() 指定的更多选项。[0]

使用顶级参数而不是 body 字段

这可能是最有影响力的变化。我们曾经使用 body 字段来指定所有与 Elasticsearch 相关的设置或搜索查询，如本文所示。现在我们需要将它们全部更改为顶级参数。它不仅影响搜索 API，还影响所有 API。例如，create API 需要更新如下：[0]

如您所见，我们只需要将 body 参数扩展为顶级参数。如果不想显式地一一指定顶级参数，可以使用字典扩展语法 **configuaration。此更改同样适用于所有 Elasticsearch API。[0]

批量 API 的更新

当我们有大量文档要索引时，我们可以使用批量 API 批量加载它们。现在语法也不同了。首先，我们需要明确指定索引。此外，我们应该使用操作而不是 body 参数来指定操作：

另请注意，在旧语法中，动作是一个长字符串，每个动作由换行符分隔。但是，在新语法中，操作可以是作为字典的操作列表，这意味着我们现在不需要将每个操作转储为 JSON 字符串。我们还可以使用带有新语法的 filter_path 参数指定要在响应中显示的字段。

API 响应现在是对象而不是字典

在之前的版本中，Elasticsearch API 的响应是字典，你通常通过 resp[‘hits’][‘hits’] 来获取结果。但是，在 Elasticsearch 8 中，响应不再是字典，而是 ObjectApiResponse 类的实例。它有两个属性，meta 和 body，可以分别用于访问请求元数据和结果。

神奇的是，我们仍然像以前一样直接访问 hits 键。但是，我们只能像字典键一样访问它，而不能像对象属性一样访问它。

这要与旧行为一致。我认为这可能会在一段时间内被弃用，因此，从身体访问命中更安全，如上所示。

使用更细粒度的错误类

在以前的版本中，TransportError 涵盖传输错误（如连接超时）和 API 错误（如未找到索引）。但是在 Elasticsearch 8 版本中，TransportError 仅涵盖传输错误，API 错误需要使用新的 ApiError，这对调试更有帮助。

在这篇文章中，我们介绍了在 Python 中使用 Elasticsearch 8 的一些重要语法更新。其中许多是重大更改，这意味着您需要更新以前的 Python 代码以使其适用于最新版本。有了这篇文章中展示的列表，代码的重构应该会更直接。您还可以参考官方文档和 GitHub 问题，以更好地了解更改的原因以及更多技术细节。[0][1]

Related articles:

• 关于在 Python 中使用 Elasticsearch 你需要知道的一切[0]