Stable API

Overview概述

In this guide, you can learn how to specify the Stable API when connecting to a MongoDB instance or replica set. You can use the Stable API feature to force the server to run operations with behavior compatible with the specified API version. 在本指南中，您可以学习如何在连接到MongoDB实例或副本集时指定Stable API。您可以使用Stable API功能强一致性务器运行行为与指定API版本兼容的操作。An API version defines the expected behavior of the operations it covers and the format of server responses. 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版本定义了它所涵盖的操作的预期行为以及服务器响应的格式。如果更改为不同的API版本，则不能保证操作是兼容的，也不能保证服务器响应是相似的。

When you use the Stable 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 Stable API.当您将Stable API功能与官方MongoDB驱动程序一起使用时，您可以更新驱动程序或服务器，而无需担心Stable API所涵盖命令的向后兼容性问题。

See the MongoDB reference page on the Stable API for more information including a list of commands it covers.请参阅Stable API上的MongoDB参考页面，了解更多信息，包括它包含的命令列表。

The following sections describe how you can enable the Stable API for your MongoDB client and the options that you can specify.以下部分描述了如何为MongoDB客户端启用Stable API以及可以指定的选项。

Enable the Stable API on a MongoDB Client在MongoDB客户端上启用稳定的API

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

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

• Specify a server URI to connect to.指定要连接的服务器URI。
• Specify a Stable 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");

// Replace the placeholders in the connection string uri with your credentials将连接字符串uri中的占位符替换为您的凭据
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";

// Create a client with options to specify Stable API Version 1创建具有指定稳定API版本1的选项的客户端
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

Stable API Options选项

You can enable or disable optional behavior related to the Stable 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");

// Replace the placeholders in the connection string uri with your credentials将连接字符串uri中的占位符替换为您的凭据
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";

/* Create a client with options to specify Stable API Version 1, return errors for commands outside of the API version, and raise exceptions for deprecated commands创建一个具有指定稳定API版本1的选项的客户端，返回API版本之外的命令错误，并引发不推荐使用的命令的异常 */
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