データの変更を監視

項目一覧

Overview

サンプルデータ
変更ストリームを開く
変更ストリームを開く例
変更ストリーム出力の変更
特定のイベントに一致する例
監視動作の変更
変更前と変更後のイメージを含めます
詳細情報
API ドキュメント

Overview

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

サンプルデータ

このガイドの例では、 Atlas サンプルデータセットのsample_restaurantsデータベース内の restaurantsコレクションを使用します。 MongoDB Atlas クラスターを無料で作成して、サンプルデータセットをロードする方法については、「 Atlas を使い始める」ガイドを参照してください。

変更ストリームを開く

変更ストリームを開くには、観察するイベントの範囲に対応する次のいずれかの関数を呼び出します。

mongoc_client_watch(): MongoDBデプロイのすべての変更を監視
mongoc_database_watch():データベース内のすべてのコレクションの変更を監視
mongoc_collection_watch():コレクションの変更を監視します

変更ストリームを開く例

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

bson_t *pipeline = bson_new ();
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch (collection, pipeline, NULL);
while (true) {
    bson_error_t error;
    if (mongoc_change_stream_next (change_stream, &doc)) {
        char *str = bson_as_canonical_extended_json (doc, NULL);
        printf ("Received change: %s\n", str);
        bson_free (str);
    } else if (mongoc_change_stream_error_document (change_stream, &error, NULL)) {
        printf("Got error on change stream: %s\n", error.message);
        break;
    }
}
bson_destroy (pipeline);
mongoc_change_stream_destroy (change_stream);

変更の監視を開始するには、アプリケーションを実行します。次に、別のアプリケーションまたはシェルで、restaurantsコレクションに対して書込み操作を実行します。次の例では、nameフィールドの値が "Blarney Castle" であるドキュメントをアップデートします。

bson_t *filter = BCON_NEW ("name", BCON_UTF8 ("Blarney Castle"));
bson_t *update = BCON_NEW("$set", "{", "cuisine", BCON_UTF8 ("Irish"), "}");
mongoc_collection_update_one (collection, filter, update, NULL, NULL, NULL);

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

{
  "_id": { ... },
  "operationType": "update",
  "clusterTime": { ... },
  "ns": {
    "db": "sample_restaurants",
    "coll": "restaurants"
  },
  "updateDescription": {
    "updatedFields": {
      "cuisine": "Irish"
    },
    "removedFields": [],
    "truncatedArrays": []
  }
  ...
}

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

変更ストリーム出力を変更するには、任意の監視関数に pipeline パラメータを渡します。このパラメーターを使用すると、指定された変更イベントのみを監視できます。パラメーターをオブジェクトのリストとして形式します。各オブジェクトは集計ステージを表します。

pipelineパラメーターでは、次のステージを指定できます。

$addFields
$match
$project
$replaceRoot
$replaceWith
$redact
$set
$unset

特定のイベントに一致する例

次の例では、pipeline パラメータを使用して $match ステージを含め、アップデート操作のみを記録する変更ストリームを開きます。

bson_t *pipeline = BCON_NEW (
    "pipeline", "[", 
    "{", "$match", "{", "operationType", BCON_UTF8 ("update"), "}", "}", 
    "]");
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch (collection, pipeline, NULL);
while (mongoc_change_stream_next (change_stream, &doc)) {
  char *str = bson_as_canonical_extended_json (doc, NULL);
  printf ("Received change: %s\n", str);
  bson_free (str);
}
bson_destroy (pipeline);
mongoc_change_stream_destroy (change_stream);

変更ストリーム出力の変更の詳細については、MongoDB Server マニュアルの「変更ストリーム出力の変更」セクションを参照してください。

監視動作の変更

関数呼び出しにオプションを渡すことで、任意の監視関数を変更できます。オプションを指定しない場合、ドライバーは操作をカスタマイズしません。

次の表では、監視関数の動作をカスタマイズするために使用できるオプションについて説明します。

オプション	説明
`batchSize`	Sets the number of documents to return per batch.
`comment`	Specifies a comment to attach to the operation.
`fullDocument`	Sets the `fullDocument` value. To learn more, see the Include Pre-Images and Post-Images section of this document.
`fullDocumentBeforeChange`	Sets the `fullDocumentBeforeChange` value. To learn more, see the Include Pre-Images and Post-Images section of this document.
`maxAwaitTimeMS`	Sets the maximum await execution time on the server for this operation, in milliseconds.

監視操作の構成に使用できるオプションの完全なリストについては、 MongoDB Serverマニュアルの監視メソッドガイドを参照してください。

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

重要

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

デフォルトでは、コレクションに対して操作を実行すると、対応する変更イベントには、その操作によって変更されたフィールドのデルタのみが含まれます。変更前または変更後の完全なドキュメントを表示するには、監視関数呼び出しで fullDocumentBeforeChange または fullDocument オプションを指定します。

変更前のイメージは、変更前のドキュメントの完全なバージョンです。変更ストリームイベントに変更前のイメージを含めるには、次のいずれかの値をfullDocumentBeforeChange オプションに渡します。

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

変更後のイメージとは、変更後のドキュメントの完全なバージョンです。変更ストリームイベントに変更後のイメージを含めるには、次のいずれかの値をオプションに渡します。fullDocument

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

次の例では、コレクションに対して mongoc_collection_watch() 関数を呼び出し、fullDocument オプションを指定して更新されたドキュメントの変更後のイメージを結果に含めます。

bson_t *pipeline = bson_new ();
bson_t *opts = BCON_NEW ("fullDocument", BCON_UTF8 ("updateLookup"));
const bson_t *doc;
mongoc_change_stream_t *change_stream =
    mongoc_collection_watch (collection, pipeline, opts);
while (true) {
    bson_error_t error;
    if (mongoc_change_stream_next (change_stream, &doc)) {
        char *str = bson_as_canonical_extended_json (doc, NULL);
        printf ("Received change: %s\n", str);
        bson_free (str);
    } else if (mongoc_change_stream_error_document (change_stream, &error, NULL)) {
        printf("Got error on change stream: %s\n", error.message);
        break;
    }
}
bson_destroy (pipeline);
bson_destroy (opts);
mongoc_change_stream_destroy (change_stream);

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

{
  "_id": ...,
  "operationType": "update",
  "clusterTime": ...,
  "wallTime": ...,
  "fullDocument": {
    "_id": {
      ...
    },
    "address": ...,
    "borough": "Queens",
    "cuisine": "Irish",
    "grades": [ ... ],
    "name": "Blarney Castle",
    "restaurant_id": ...
  },
  "ns": {
    "db": "sample_restaurants",
    "coll": "restaurants"
  },
  "documentKey": {
    "_id": ...
  },
  "updateDescription": {
    "updatedFields": {
      "cuisine": "Irish"
    },
    "removedFields": [],
    "truncatedArrays": []
  }
}

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

詳細情報

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

API ドキュメント

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

戻る

カーソルからのデータへのアクセス

Indexes