/ /

データの変更を監視

Overview

このガイドでは、変更ストリームを使用してデータベースへのリアルタイムの変更を監視する方法を学習できます。変更ストリームは、アプリケーションがコレクション、データベース、または配置のデータ変更をサブスクライブできる MongoDB Server の機能です。

C++ドライバーを使用すると、 mongocxx::change_streamをインスタンス化してデータの変更を監視できます。

サンプルデータ

このガイドの例では、 Atlasサンプルデータセットのsample_restaurantsデータベースのrestaurantsコレクションを使用します。 C++アプリケーションからこのコレクションにアクセスするには、Atlasmongocxx::client クラスターに接続するをインスタンス化し、次の値をdb 変数とcollection 変数に割り当てます。

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

MongoDB Atlasクラスターを無料で作成して、サンプルデータセットをロードする方法については、MongoDBを使い始めるガイドを参照してください。

変更ストリームを開く

変更ストリームを開くには、 watch()メソッドを呼び出します。 watch()メソッドを呼び出すインスタンスによって、変更ストリームがリッスンするイベントの範囲が決まります。次のクラスでwatch()メソッドを呼び出すことができます。

mongocxx::client: MongoDBデプロイのすべての変更を監視
mongocxx::database:データベース内のすべてのコレクションの変更を監視
mongocxx::collection:コレクションの変更を監視

次の例では、 restaurantsコレクションの変更ストリームを開き、変更が発生に応じて出力します。

auto stream = collection.watch();
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

変更の監視を開始するには、上記のコードを実行します。次に、別のアプリケーションまたはshellで、restaurantsコレクションを変更します。次の例では、 nameフィールドの値がBlarney Castleであるドキュメントを更新します。

auto result = collection.update_one(make_document(kvp("name", "Blarney Castle")), 
                                    make_document(kvp("$set", 
                                    make_document(kvp("cuisine", "Irish")))));

コレクションを更新すると、変更ストリームアプリケーションは変更が発生に応じて出力します。出力される変更イベントは、次の出力のようになります。

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... }, "wallTime" : { "$date" : ... }, "ns" :
{ "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" :
{ "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" :
{ "cuisine" : "Irish" }, "removedFields" : [  ], "truncatedArrays" : [  ] } }

変更ストリーム出力の変更

変更ストリーム出力を変更するには、 mongocxx::pipelineインスタンスをwatch()メソッドの引数として渡します。次のリストには、対応する setter メソッドを呼び出して設定できる一部のmongocxx::pipelineフィールドが含まれています。

add_fields: ドキュメントに新しいフィールドを追加します
match: ドキュメントをフィルタリングします
project:ドキュメントフィールドのサブセットをプロジェクションします
redact: ドキュメントのコンテンツを制限します
group: 指定した式でドキュメントをグループ化します
merge: 結果をコレクションに出力します

Tip

mongocxx::pipeline フィールドの完全なリストについては、 mongocx::パイプライン APIドキュメントを参照してください。

次の例では、 mongocxx::pipelineインスタンスのmatchフィールドを設定し、パイプラインをwatch()メソッドに渡します。これはwatch()メソッドに更新操作のみを出力するように指示します。

mongocxx::pipeline pipeline;
pipeline.match(make_document(kvp("operationType", "update")));
auto stream = collection.watch(pipeline);
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

`watch()` 動作を変更する

mongocxx::options::change_streamクラスのインスタンスをパラメーターとして渡すことで、 watch()メソッドの動作を変更できます。次の表では、 mongocxx::options::findインスタンスで設定できるフィールドを説明しています。

フィールド	説明
`full_document`	ドキュメントに加えられた変更のみを表示するのではなく、変更後に完全なドキュメントを表示するかどうかを指定します。このオプションの詳細については、「変更前イメージと変更後イメージを含める」を参照してください。
`full_document_before_change`	ドキュメントに加えられた変更のみを表示するのではなく、変更前のドキュメント全体を表示するかどうかを指定します。このオプションの詳細については、「変更前イメージと変更後イメージを含める」を参照してください。
`resume_after`	`watch()`再開トークンで指定された操作の後に変更を返すことを再開するように指示します。各変更ストリームのイベントドキュメントには、フィールドとして再開トークンが含まれています。変更後に再開する操作を表す変更イベントドキュメントの `_id_id`フィールド全体を渡します。 `resume_after` はおよび`start_after` `start_at_operation_time`と排他関係にあります。
`start_after`	`watch()`再開トークンで指定された操作の後に新しい変更ストリームを開始するよう、に指示します。このフィールドにより、無効化イベントの後に通知を再開できます。各変更ストリームのイベントドキュメントには、フィールドとして再開トークンが含まれています。変更後に再開する操作を表す変更イベントドキュメントの `_id_id`フィールド全体を渡します。 `start_after` `resume_after`はおよび`start_at_operation_time` と排他関係にあります。
`start_at_operation_time`	`watch()`指定されたタイムスタンプ後に発生したイベントのみを返すように `start_at_operation_time` `resume_afterstart_after`に指示します。はおよびと排他関係にあります。
`max_await_time_ms`	空のバッチするを返す前に、新しいデータ変更が変更ストリームカーソルに報告されるまでサーバーが待機する最大時間をミリ秒単位で設定します。デフォルトは 1000 ミリ秒です。
`batch_size`	MongoDBクラスターからのレスポンスの各バッチするで返す変更イベントの最大数を設定します。
`collation`	変更ストリームカーソルに使用する照合を設定します。
`comment`	操作にコメントを付けます。

変更前と変更後のイメージを含めます

重要

配置で MongoDB v 6.0以降が使用されている場合にのみ、コレクションで変更前と変更後のイメージを有効にできます。

デフォルトでは、コレクションに対して操作を実行すると、対応する変更イベントには、その操作によって変更されたフィールドのデルタのみが含まれます。変更前または変更後の完全なドキュメントを表示するには、インスタンスのフィールドまたはfull_document_before_change full_documentmongocxx::options::change_streamフィールドを指定します。

変更前のイメージは、変更前のドキュメントの完全なバージョンです。変更ストリームイベントに変更前のイメージを含めるには、 full_document_before_changeフィールドを次のいずれかの文字列に設定します。

"whenAvailable": 変更イベントには、変更前のイメージが利用可能な場合にのみ、変更イベント用の変更されたドキュメントの変更前のイメージが含まれます。
"required": 変更イベントには、変更イベント用に変更されたドキュメントの変更前のイメージが含まれます。変更前のイメージが利用できない場合、ドライバーはエラーを発生させます。

変更後のイメージとは、変更後のドキュメントの完全なバージョンです。変更ストリームイベントに変更後のイメージを含めるには、 full_documentフィールドを次のいずれかの文字列に設定します。

"updateLookup": 変更イベントには、変更後一定時間の変更されたドキュメント全体のコピーが含まれます。
"whenAvailable": 変更イベントには、変更後のイメージが利用可能な場合にのみ、変更イベント用の変更されたドキュメントの変更後のイメージが含まれます。
"required": 変更イベントには、変更イベントの変更されたドキュメントの変更後のイメージが含まれます。変更後のイメージが利用できない場合、ドライバーはエラーを発生させます。

次の例では、コレクションでwatch()メソッドを呼び出し、 mongocxx::options::change_streamインスタンスのfull_documentフィールドを設定して更新されたドキュメントの変更後のイメージを含めます。

mongocxx::options::change_stream opts;
opts.full_document("updateLookup");
auto stream = collection.watch(opts);
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

を実行中している変更ストリームアプリケーションで、前述の更新例を使用してrestaurantsコレクション内のドキュメントを更新すると、次のコードのような変更イベントが出力されます。

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : ... },
"fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : "202-24",
"coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" :
"Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", "cuisine" :
"Irish", "grades" : [ ... ], "name" : "Blarney Castle", "restaurant_id" : "40366356" },
"ns" : { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" :
{ "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" :
{ "cuisine" : "Irish" }, "removedFields" : [  ], "truncatedArrays" : [  ] } }

Tip

変更前と変更後のイメージの詳細については、Change Streams MongoDB Serverマニュアルの「とドキュメントの変更前イメージおよび変更後イメージ」を参照してください。

詳細情報

Change Streams変更ストリームの詳細については、MongoDB Server マニュアルの「ストリーム」を参照してください。

API ドキュメント

このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。

戻る

Cursors

Write Data