注意
Stable API 機能には MongoDB Server 5.0 以降が必要です。
Overview
このガイドでは、MongoDB 配置に接続するときにStable API互換性を指定する方法を学習できます。
Stable API 機能を使用すると、指定された API バージョンと互換性のある動作でサーバーに操作が強制的に実行されます。 Stable API を使用すると、サーバーからの一貫した応答が確保され、アプリケーションの API の長期的な安定性が確保されます。
次のセクションでは、 MongoDBクライアントの Stable API を有効にしてカスタマイズする方法について説明します。サポートするコマンドのリストを含む、Stable APIの詳細については、 MongoDB Serverマニュアルの Stable API を参照してください。
Stable API を有効にする
Stable API を有効にするには、 Mongo::Clientインスタンスを作成するときに、Stable APIバージョンを指定するハッシュを任意の server_api パラメータに渡します。
次のコード例は、Stable API バージョン1を指定する方法を示しています。
client = Mongo::Client.new(uri, server_api: { version: '1' })
指定されたAPIバージョンで Clientインスタンスを作成すると、クライアントで実行するすべてのコマンドが指定されたバージョンを使用します。 Stable APIの複数のバージョンを使用してコマンドを実行する必要がある場合は、新しい Client を作成します。
Stable API の構成
次の表では、server_api ハッシュで指定して設定できる Stable APIオプションについて説明しています。これらのオプションを使用して、 Stable APIの動作をカスタマイズできます。
オプション名 | 説明 |
|---|---|
厳密 | Optional. When true, if you call a command that isn't part of
the declared API version, the driver raises an exception.Default: false |
delete_errors | Optional. When true, if you call a command that is deprecated in the
declared API version, the driver raises an exception.Default: false |
次のコード例は、ServerApiインスタンスで 2 つのオプションを設定する方法を示しています。
client = Mongo::Client.new(uri, server_api: { version: '1', strict: true, deprecation_errors: true })
トラブルシューティング
次のセクションでは、 Stable APIを使用するときに発生する可能性のある一般的な問題について説明します。
サーバー上の認識されないフィールド 'apiVersion'
APIバージョンを指定し、 Stable APIをサポートしていないMongoDBサーバーに接続すると、 Rubyドライバーはこの例外を発生させます。MongoDB Server v5.0 以降を実行中配置に接続していることを確認してください。
apiStrict:true は提供されていますが、コマンド数は API バージョンではありません
指定した Stable APIバージョンに含まれない操作をClient が実行する場合、 Rubyドライバーはこの例外を発生させます。このエラーを回避するには、指定された Stable APIバージョンでサポートされている別の操作を使用するか、ServerApiオブジェクトの構築時に strict オプションを false に設定します。
API ドキュメント
Rubyドライバーで Stable APIを使用する方法の詳細については、次のAPIドキュメントを参照してください。