Versioned API版本化API¶

Overview概述¶

In this guide, you can learn how to specify the Versioned API when connecting to a MongoDB instance or replica set. 在本指南中，您可以了解如何在连接到MongoDB实例或副本集时指定版本化API。You can use the Versioned API feature to force the server to run operations with behavior compatible with the specified API version. 您可以使用版本化API功能强一致性务器运行行为与指定API版本兼容的操作。An API version defines the expected behavior of the operations it covers and the format of server responses. API版本定义了它所涵盖的操作的预期行为以及服务器响应的格式。If you change to a different API version, the operations are not guaranteed to be compatible and the server responses are not guaranteed to be similar.如果更改为其他API版本，则不能保证操作兼容，也不能保证服务器响应类似。

When you use the Versioned API feature with an official MongoDB driver, you can update your driver or server without worrying about backward compatibility issues of the commands covered by the Versioned API.在官方MongoDB驱动程序中使用版本化API功能时，可以更新驱动程序或服务器，而无需担心版本化API所涵盖命令的向后兼容性问题。

See the server manual page on the Versioned API for more information including a list of commands it covers.请参阅版本化API上的服务器手册页面，以了解更多信息，包括其中包含的命令列表。

The following sections describe how you can enable the Versioned API for your MongoDB client and the options that you can specify.以下各节介绍如何为MongoDB客户端启用版本化API以及可以指定的选项。

Enable the Versioned API on a MongoDB Client在MongoDB客户端上启用版本化API¶

To enable the Versioned API, you must specify an API version in the MongoClientOptions passed to your MongoClient. 要启用版本化API，必须在传递给MongoClient的MongoClientOptions中指定API版本。Once you instantiate a MongoClient instance with a specified API version, all commands you run with that client use that version of the Versioned API.使用指定的API版本实例化MongoClient实例后，与该客户端一起运行的所有命令都将使用该版本的API。

The example below shows how you can instantiate a MongoClient that sets the Versioned API version and connects to a server by performing the following operations:下面的示例显示了如何通过执行以下操作来实例化设置版本化API版本并连接到服务器的MongoClient：

• Specify a server URI to connect to.指定要连接到的服务器URI。
• Specify a Versioned API version in the MongoClientOptions object, using a constant from the ServerApiVersion object.使用ServerApiVersion对象中的常量，在MongoClientOptions对象中指定版本化的API版本。
• Instantiate a MongoClient, passing the URI and the MongoClientOptions to the constructor.实例化MongoClient，将URI和MongoClientOptions传递给构造函数。

const { MongoClient, ServerApiVersion } = require("mongodb");

const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });

MongoParseError: Invalid server API version=...

For more information on the methods and classes referenced in this section, see the following API Documentation:有关本节中引用的方法和类的更多信息，请参阅以下API文档：

• ServerApiVersion
• MongoClientOptions
• MongoClient

Versioned API Options版本化API选项¶

You can enable or disable optional behavior related to the Versioned API as described in the following table.您可以启用或禁用与版本化API相关的可选行为，如下表所述。

The following example shows how you can set the options of the ServerApi interface.以下示例显示如何设置ServerApi接口的选项。

const { MongoClient, ServerApiVersion } = require("mongodb");

const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri,
    {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    });

For more information on the options in this section, see the following API Documentation:有关本节中选项的更多信息，请参阅以下API文档：

• ServerApi