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インスタンスを使用して接続するサーバーを指定します。MongoClient.create()メソッドを使用してMongoClientをインスタンス化し、MongoClientSettingsインスタンスをパラメーターとして渡します。
val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .build() // Replace the uri string placeholder with your MongoDB deployment's connection string val uri = "<connection string>" val settings = MongoClientSettings.builder() .applyConnectionString(ConnectionString(uri)) .serverApi(serverApi) .build() val client = MongoClient.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 つのオプションを設定する方法を示しています。
val serverApi = ServerApi.builder() .version(ServerApiVersion.V1) .strict(true) .deprecationErrors(true) .build()
このセクションのオプションの詳細については、次の API ドキュメントを参照してください。