Stable API

項目一覧

Stable API とは何であり、使用する必要があるのか？

下位互換性の保証
API バージョンの宣言
クライアント API バージョンの確認
Strict クライアントの作成
Stable API コマンドへの移行
Stable API 外のコマンドと機能を使用する方法
Stable API コマンド
パラメーター
動作
Stable API エラー応答

Stable API とは何であり、使用する必要があるのか？

MongoDB Stable API（以前は Versioned API と呼ばれていました）を使用すると、MongoDB サーバーを自由にアップグレードでき、MongoDB バージョン間の動作変更によってアプリケーションが壊れないようにすることができます。

MongoDB 5.0 では、MongoDB サーバー製品と通信するアプリケーション用の Stable API が導入されています。Stable API を使用すると、アプリケーションを実行する MongoDB API のバージョンを指定できます。

Stable API は、アプリケーション用 API の長期的な安定性を提供し、より頻繁なリリースとサーバーの自動アップグレードをサポートします。これにより、アプリケーションは、重大な変更のリスクを負うことなく、迅速にリリースされた機能を活用できるようになります。

apiVersion を明示的に指定しない場合でも、ドライバー接続のデフォルトの動作は期待どおりに機能し続けます。

Stable API には、アプリケーションがデータの読み取りと書き込み、コレクションとインデックスの作成、その他の一般的なタスクの実行に使用する MongoDB コマンドのサブセットが含まれています。

注意

2022 年 2 月より、「Versioned API」の用語が「Stable API」に変更されました。この用語の変更によるコンセプトと機能についての変更はありません。

下位互換性の保証

サーバーのアップグレードによってアプリケーションの動作に大きな変化が生じることはありません。この保証は、新しいサーバーが指定された API バージョンをサポートしている限り有効です。

下位互換性を保証するには、アプリケーションで次のことを行う必要があります。

API バージョンを宣言する
指定した API バージョンでサポートされているコマンドと機能のみを使用する
公式ドライバーのサポートされているバージョンを使用して配置する

API バージョンの宣言

➤ 右上の言語の選択のドロップダウンメニューを使用して、このページの例の言語を設定します。

Stable API を使用するには、最新のドライバーにアップグレードし、アプリケーションの MongoClient を作成します。

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")};
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIExample is an example of creating a client with stable API.
func StableAPIExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build()
                ).build()
        );
return client;

    from pymongo.server_api import ServerApi
    client = AsyncIOMotorClient(uri, server_api=ServerApi("1"))

client = new MongoClient(uri, { serverApi: { version: '1' } });

$serverApi = new \MongoDB\Driver\ServerApi('1');
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

from pymongo.server_api import ServerApi
MongoClient(uri, server_api=ServerApi("1"))

client = Mongo::Client.new(uri_string, server_api: {version: "1"})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1)
    )
    let client = try MongoClient(uri, options: opts)

"1" は現在、使用可能な唯一の API バージョンです。

デフォルトでは、クライアントは non-strict です。non-strict クライアントでは、Stable API に属しているかどうかに関係なく、任意のコマンドを実行できます。

クライアント API バージョンの確認

アプリケーションに設定されている API バージョンを確認するには、 serverStatusコマンドを使用します。 MongoDB インスタンスに接続されているアプリケーションごとに、 apiVersionsドキュメントにappnameが表示されます。

詳細については、「metrics.apiVersions」を参照してください。

db.runCommand( { serverStatus: 1 } ).metrics.apiVersions

Strict クライアントの作成

strict クライアントは、Stable API 以外のコマンドをすべて拒否します。Stable API 外でコマンドを使用しようとすると、APIVersionError 応答が返されます。

strict クライアントは、クエリの計画および実行中にサポートされていないインデックスの型も無視します。

サンプルコードを使用して、strict クライアントを作成します。

mongosh --apiVersion 1 --apiStrict

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, true);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(true);  // Enable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: true);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPIStrictExample is an example of creating a client with strict stable API.
func StableAPIStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(true)
                .build()
                ).build()
        );
return client;

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=True))

client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });

$serverApi = new \MongoDB\Driver\ServerApi('1', true);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=True))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: true})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(true)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: true)
    )
    let client = try MongoClient(uri, options: opts)

Stable API コマンドへの移行

アプリケーションを Stable API を使用するように移行するには、次の手順を実行する必要があります。

新しい MongoClient オプションを使用してアプリケーションのテストスイートを実行します。
Stable API 外で使用するコマンドと機能を特定します。
Stable API の代替コマンドと機能に移行します。

アプリケーションが Stable API で定義されたコマンドと機能のみを使用したら、新しい MongoClient オプションを使用して再度デプロイでき、将来のサーバーのアップグレードがアプリケーションに悪影響を与えないよう確実になります。

Stable API 外のコマンドと機能を使用する方法

Stable API 外のコマンドや機能を使用するには、non-strict クライアントを使用してデプロイに接続できます。デフォルトでは、クライアントは non-strict です。

non-strict クライアントを作成するには、以下のサンプルコードを使用します。

mongosh --apiVersion 1

mongoc_client_t *client = NULL;
mongoc_server_api_t *server_api = NULL;
mongoc_server_api_version_t server_api_version;
bson_error_t error;
/* For a replica set, include the replica set name and a seedlist of the
 * members in the URI string; e.g.
 * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \
 *    "27017/?replicaSet=myRepl";
 * client = mongoc_client_new (uri_repl);
 * For a sharded cluster, connect to the mongos instances; e.g.
 * uri_sharded =
 * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/";
 * client = mongoc_client_new (uri_sharded);
 */
/* Create a mongoc_client_t without server API options configured. */
client = get_client_for_version_api_example ();
mongoc_server_api_version_from_string ("1", &server_api_version);
server_api = mongoc_server_api_new (server_api_version);
mongoc_server_api_strict (server_api, false);
assert (mongoc_client_set_server_api (client, server_api, &error));

using namespace mongocxx;
uri client_uri{"mongodb://localhost"};
// Create an option set for API v1
const auto server_api_opts =
    options::server_api{options::server_api::version_from_string("1")}
        .strict(false);  // Explicitly disable strict mode for the server API
// Store it in the set of client options
const auto client_opts =
    options::client{}
        .server_api_opts(server_api_opts); // Set the version and options
// Create a new client with the options
mongocxx::client client{client_uri, client_opts};

var connectionString = "mongodb://localhost";
var serverApi = new ServerApi(ServerApiVersion.V1, strict: false);
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
mongoClientSettings.ServerApi = serverApi;
var mongoClient = new MongoClient(mongoClientSettings);

// StableAPINonStrictExample is an example of creating a client with non-strict stable API.
func StableAPINonStrictExample() {
	ctx := context.TODO()
	// For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g.
	// uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl"
	// For a sharded cluster, connect to the mongos instances; e.g.
	// uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"
	uri := mtest.ClusterURI()
	serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(false)
	clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions)
	client, err := mongo.Connect(clientOpts)
	if err != nil {
		panic(err)
	}
	defer func() { _ = client.Disconnect(ctx) }()
}

MongoClient client = MongoClients.create(
        MongoClientSettings.builder()
        .applyConnectionString(new ConnectionString(<connection string>))
        .serverApi(
                ServerApi.builder()
                .version(ServerApiVersion.V1)
                .strict(false)
                .build()
                ).build()
        );

    client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=False))

client = new MongoClient(uri, { serverApi: { version: '1', strict: false } });

$serverApi = new \MongoDB\Driver\ServerApi('1', false);
$client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);

MongoClient(uri, server_api=ServerApi("1", strict=False))

client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: false})

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
    .version(ServerApiVersion::V1)
    .strict(false)
    .build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)

    let opts = MongoClientOptions(
        serverAPI: MongoServerAPI(version: .v1, strict: false)
    )
    let client = try MongoClient(uri, options: opts)

この non-strict クライアントを使えば、Stable API 以外のコマンドを実行できます。たとえば、この non-strict クライアントでは、createUser コマンドを実行できます。

重要

Stable API 外のコマンドと機能には、バージョン化された代替手段と同じ下位互換性の保証はありません。

Stable API コマンド

Stable API V1 に含まれるデータベースコマンドは、使用している MongoDB のバージョンによって異なります。Stable API に含まれるデータベースコマンドと、それらが導入された MongoDB のバージョンを確認するには、「Stable API の変更ログ」を参照してください。

パラメーター

アプリケーションの MongoDB ドライバー接続コードで、Stable API の次の任意のパラメーターを指定できます。詳細については、アプリケーションで使用するドライバーの MongoDB ドライバーのドキュメントを確認してください。

Parameter	タイプ	説明
apiVersion	string	API バージョンを指定します。`"1"` は現在サポートされている唯一のバージョンです。
apiStrict	ブール値	`true`場合: 宣言した API バージョンに含まれないコマンドを使用すると、 APIStrictErrorエラーが返されます。 Stable API でサポートされていないインデックスは、クエリプランナーによって無視されます。 apiStrictを指定する場合は、 apiVersionも指定する必要があります。指定しない場合、デフォルトで `false` になります。
apiDeprecationErrors	ブール値	`true`の場合、指定された API バージョンで非推奨のコマンドまたは動作を使用すると、 APIDeprecationErrorが返されます。 apiDeprecationErrorsを指定する場合は、 apiVersionも指定する必要があります。指定しない場合、デフォルトで `false` になります。

動作

Parameter Validation

MongoDB 5.0 以降、API V1 データベースコマンドは、コマンドによって明示的に受け入れられないパラメーターを渡された場合にエラーを発生させます。

Stable API エラー応答

この表は、問題のある Stable API リクエストに対するエラー応答を示しています。

サーバー応答	リクエスト
APIDeprecationError	`V` の API バージョンで `{ apiDeprecationErrors: true }` を指定し、`V` で非推奨の動作を使用します。
APIStrictError	`V` の API バージョンで `{ apiStrict: true }` を指定していますが、`V` バージョンにはない動作を使用しています。
APIVersionError	サーバーがサポートしていないapiVersionを指定します。
無効なオプション	`{ apiStrict: true }`または`{ apiDeprecationErrors: true }`を指定しますが、 apiVersion は省略します。

戻る

サーバーセッション

後のバージョンへの移行