稳定 API

本页

概述

启用稳定 API
配置稳定 API
API 文档

注意

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

概述

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

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

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

启用稳定API

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

构建一个mongoc_server_api_t对象并指定一个稳定API版本。您必须使用在mongoc_server_api_t枚举中定义的稳定API版本。
构建一个mongoc_client_t对象。
将客户端和稳定API对象传递给mongoc_client_set_server_api函数。

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

#include <mongoc/mongoc.h>
int main ()
{
    bson_error_t error;
    mongoc_init ();
    mongoc_server_api_t *stable_api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
    mongoc_client_t *client = mongoc_client_new ("<connection string>");
    if (!mongoc_client_set_server_api (client, stable_api, &error))
    {
        fprintf (stderr, "Failed to set Stable API: %s\n", error.message);
        return EXIT_FAILURE;
    }
    // Use the client for operations...
    mongoc_server_api_destroy (stable_api);
    mongoc_cleanup ();
    return EXIT_SUCCESS;
}

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

配置稳定API

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

选项名称	描述
strict	可选。当设置为`true`时，如果调用不属于声明API版本的命令，驱动程序将引发异常。默认：false
deprecation_errors	可选。当设置为`true`时，如果调用在声明API版本中已弃用的命令，驱动程序将引发异常。默认：false

以下代码示例显示了如何在构造ServerApi对象时将这两个选项设置为true

mongoc_server_api_t *stable_api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
mongoc_server_api_strict (stable_api, true);
mongoc_server_api_deprecation_errors (stable_api, true);
mongoc_client_t *client = mongoc_client_new ("<connection string>");
if (!mongoc_client_set_server_api (client, stable_api, &error)) {
    fprintf (stderr, "Failed to set Stable API: %s\n", error.message);
    return EXIT_FAILURE;
}

API文档

有关使用C驱动程序与稳定API一起使用的信息，请参阅以下API文档

创建 MongoClient

下一步

选择连接目标