Stable API
注意
Stable API 機能には MongoDB Server 5.0 以降が必要です。
接続するすべての MongoDB サーバーがこの機能をサポートしている場合にのみ、Stable API 機能を使用する必要があります。
Overview
このガイドでは、MongoDB インスタンスまたはレプリカセットに接続するときにStable APIを指定する方法を学習できます。 Stable API 機能を使用すると、指定されたAPI バージョンと互換性のある動作で操作をサーバーが強制的に実行することができます。 API バージョンは、カバーされる操作に期待される動作とサーバー応答の形式を定義します。 別の API バージョンに変更した場合、操作は互換性が保証されず、サーバー応答が類似することは保証されません。
公式の MongoDB ドライバーで Stable API 機能を使用すると、Stable API でカバーされるコマンドの下位互換性の問題を心配することなく、ドライバーまたはサーバーを更新できます。
カバーされるコマンドのリストなどの詳細については、 Stable APIの MongoDB リファレンス ページを参照してください。
次のセクションでは、MongoDB クライアントに対して Stable API を有効にする方法と、指定できるオプションについて説明します。
MongoDB クライアントでの Stable API の有効化
Stable API を有効にするには、MongoDB クライアントの設定で API バージョンを指定する必要があります。 指定された API バージョンで MongoClientインスタンスをインスタンス化すると、そのクライアントで実行されるすべてのコマンドによって、そのバージョンの Stable API が使用されます。
Tip
Stable API の複数のバージョンを使用するコマンドを実行するには、そのバージョンの個別のクライアントをインスタンス化します。
Stable API でカバーされていないコマンドを実行するには、"strict" オプションが無効になっていることを確認します。 詳細については、 Stable API オプションのセクションを参照してください。
次の例では、Stable API バージョンを設定し、サーバーに接続するMongoClientをインスタンス化し、次の操作を実行する方法を示しています。
ServerApi.Builderヘルパー クラスを使用してServerApiインスタンスを構築します。ServerApiVersionクラスの定数を使用して Stable API バージョンを指定します。MongoClientSettings.Builderクラスを使用してMongoClientSettingsインスタンスを構築します。ServerAddressインスタンスを使用して接続するサーバーを指定します。MongoClients.create()メソッドを使用してMongoClientをインスタンス化し、MongoClientSettingsインスタンスをパラメーターとして渡します。
ServerApi serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .build(); // Replace the uri string with your MongoDB deployment's connection string String uri = "<connection string uri>"; MongoClientSettings settings = MongoClientSettings.builder() .applyConnectionString(new ConnectionString(uri)) .serverApi(serverApi) .build(); MongoClient client = MongoClients.create(settings);
警告
API バージョンを指定し、Stable API をサポートしていない MongoDB 配置に接続すると、MongoDB 配置でコマンドを実行するときにアプリケーションが例外を発生させる可能性があります。 API バージョンを指定するMongoClientを使用して、サポートしていないサーバーをクエリすると、クエリは失敗し、次のテキストを含む例外メッセージが表示されることがあります。
'Unrecognized field 'apiVersion' on server...
このセクションで参照されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。
Stable API オプション
次の表に示すように、Stable API に関連するオプションの動作を有効または無効にすることができます。
オプション名 | 説明 |
|---|---|
厳密 | Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception. Default: false |
DeprecationErrors | Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception. Default: false |
次の例えは、 ServerApi.Builderのメソッドを連鎖させることで、 ServerApiのインスタンスに 2 つのオプションを設定する方法を示しています。
ServerApi serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .strict(true) .deprecationErrors(true) .build();
このセクションのオプションの詳細については、次の API ドキュメントを参照してください。