Docs Menu
Docs Home
/
MongoDBマニュアル
/

Stable API

項目一覧

  • Stable API とは何であり、使用する必要があるのか?
  • 下位互換性の保証
  • API バージョンの宣言
  • クライアント API バージョンの確認
  • Strict クライアントの作成
  • 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 バージョンでサポートされているコマンドと機能のみを使用する

  • 公式ドライバーのサポートされているバージョンを使用して配置する


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


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

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

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

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 を使用するように移行するには、次の手順を実行する必要があります。

  1. 新しい MongoClient オプションを使用してアプリケーションのテスト スイートを実行します。

  2. Stable API 外で使用するコマンドと機能を特定します。

  3. Stable API の代替コマンドと機能に移行します。

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

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

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

Parameter
タイプ
説明

string

API バージョンを指定します。"1" は現在サポートされている唯一のバージョンです。

ブール値

true場合:

apiStrict を指定する場合は、 apiVersion も指定する必要があります。

指定しない場合、デフォルトで false になります。

ブール値

trueの場合、指定されたAPIバージョンで非推奨のコマンドまたは動作を使用すると、 APIDeprecationError が返されます。 apiDeprecationErrors を指定する場合は、 apiVersion も指定する必要があります。

指定しない場合、デフォルトで false になります。

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

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

サーバー応答
リクエスト

V の API バージョンで { apiDeprecationErrors: true } を指定し、V で非推奨の動作を使用します。

V の API バージョンで { apiStrict: true } を指定していますが、V バージョンにはない動作を使用しています。

サーバーがサポートしていない apiVersion を指定します。

{ apiStrict: true }{ apiDeprecationErrors: true }または を指定しますが、apiVersion は省略します。

戻る

サーバー セッション