文档菜单

文档首页 → 开发应用程序 → Python 驱动 → PyMongo

稳定的 API

本页内容

  • 概述
  • 启用稳定 API
  • 配置稳定 API
  • 故障排除
  • 服务器上出现未识别的字段 'apiVersion'
  • 提供了 apiStrict:true，但命令计数不在 API 版本中
  • API 文档

注意

稳定 API 功能需要 MongoDB 服务器 5.0 或更高版本。

概述

在本指南中，您可以了解如何在连接到 MongoDB 部署时指定 稳定 API 兼容性。

稳定 API 功能强制服务器以与您指定的 API 版本兼容的行为运行操作。当您更新驱动程序或服务器时，API 版本会更改，这可能会改变这些操作的行为。使用稳定 API 确保服务器响应的一致性，并为您的应用程序提供长期的 API 稳定性。

以下各节描述了您如何为 MongoDB 客户端启用和自定义稳定 API。有关稳定 API 的更多信息，包括它支持的命令列表，请参阅 MongoDB 服务器手册中的稳定 API。

启用稳定 API

要启用稳定 API，请执行以下步骤

  1. 构建一个ServerApi 对象并指定一个稳定的 API 版本。您必须使用在 ServerApiVersion 枚举中定义的稳定 API 版本。

  2. 构建一个 MongoClient 对象，传入您的 ServerApi 对象作为 server_api 参数。

以下代码示例展示了如何指定稳定 API 版本 1

from pymongo import MongoClient
from pymongo.server_api import ServerApi
client = MongoClient("mongodb://<username>:<password>@<hostname:<port>",
                     server_api=ServerApi("1"))

一旦您创建了一个指定 API 版本的 MongoClient 实例，所有通过客户端运行的命令都将使用指定的版本。如果您需要使用稳定 API 的多个版本运行命令，请创建一个新的 MongoClient。

配置稳定 API

以下表格描述了 ServerApi 类的参数。您可以使用这些参数来自定义稳定 API 的行为。

选项名称
描述
strict
可选。当 True 时，如果您调用不属于声明 API 版本中的命令，驱动程序将引发异常。

默认：False
deprecation_errors
可选。当 True 时，如果您调用在声明 API 版本中已弃用的命令，驱动程序将引发异常。

默认：False

以下代码示例展示了如何在构建 ServerApi 对象时使用这些参数

from pymongo import MongoClient
from pymongo.server_api import ServerApi
client = MongoClient("mongodb://<username>:<password>@<hostname:<port>",
                     server_api=ServerApi("1",
                     strict=True,
                     deprecation_errors=True))

故障排除

服务器上的未识别字段 'apiVersion'

如果指定了 API 版本并连接到不支持稳定 API 的 MongoDB 服务器，PyMongo 将引发此异常。请确保您正在连接到运行 MongoDB Server v5.0 或更高版本的部署。

提供了 apiStrict：true，但命令计数不在 API 版本中

如果您的 MongoClient 运行了一个不在您指定的稳定 API 版本中的操作，PyMongo 将引发此异常。为了避免此错误，使用由指定的稳定 API 版本支持的替代操作，或在与您的 ServerApi 对象构造时将 strict 选项设置为 False。

API 文档

有关使用 PyMongo 与稳定 API 的更多信息，请参阅以下 API 文档

← 自定义服务器选择
限制服务器执行时间"> →

本页内容