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 を有効にするには、 MongoClientに渡される MongoClientOptionsで API バージョンを指定する必要があります。 指定された API バージョンでMongoClientインスタンスをインスタンス化すると、そのクライアントで実行されるすべてのコマンドがそのバージョンの Stable API を使用します。

以下の例では、Stable API バージョンを設定し、サーバーに接続するMongoClientをインスタンス化し、次の操作を実行する方法を示しています。

• 接続するサーバー URI を指定します。

• ServerApiVersionオブジェクトの定数を使用して、 MongoClientOptionsオブジェクトに Stable API バージョンを指定します。

• URI とMongoClientOptionsをコンストラクターに渡して、 MongoClientをインスタンス化します。

const { MongoClient, ServerApiVersion } = require("mongodb");
// Replace the placeholders in the connection string uri with your credentials
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
// Create a client with options to specify Stable API Version 1
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });

MongoParseError: Invalid server API version=...

このセクションで参照されるメソッドとクラスの詳細については、次の API ドキュメントを参照してください。

• ServerApiVersion

• MongoClientOptions

• MongoClient

Stable API オプション

次の表に示すように、Stable API に関連するオプションの動作を有効または無効にすることができます。

次の例は、 ServerApiインターフェースのオプションを設定する方法を示しています。

const { MongoClient, ServerApiVersion } = require("mongodb");
// Replace the placeholders in the connection string uri with your credentials
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
/* Create a client with options to specify Stable API Version 1, return
errors for commands outside of the API version, and raise exceptions
for deprecated commands */
const client = new MongoClient(uri,
    {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    });

このセクションのオプションの詳細については、次の API ドキュメントを参照してください。

• ServerApi