稳定 API

本页内容

概述

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

注意

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

概述

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

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

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

启用稳定API

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

构建一个ServerApi对象，并指定稳定API版本。您必须使用在ServerApiVersion枚举中定义的稳定API版本。
构建一个MongoClient对象，将您的ServerApi对象作为server_api参数传递。

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

from pymongo import MongoClient
from pymongo.server_api import ServerApi
client = MongoClient("mongodb://<db_username>:<db_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://<db_username>:<db_password>@<hostname:<port>",
                     server_api=ServerApi("1",
                     strict=True,
                     deprecation_errors=True))

故障排除

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

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

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

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

API文档

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

自定义服务器选择

限制服务器执行时间