データの変更を監視

項目一覧

Overview

サンプルデータ
変更ストリームを開く
変更ストリーム出力の変更
watch()の動作を変更
変更前と変更後のイメージを含めます
詳細情報
API ドキュメント

Overview

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

MongoDB PHPライブラリを使用する場合、 watch()メソッドを呼び出してMongoDB\ChangeStreamのインスタンスを返すことができます。次に、 MongoDB\ChangeStreamインスタンスを反復処理して、アップデート、挿入、削除などのデータ変更を監視できます。

サンプルデータ

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

$collection = $client->sample_restaurants->restaurants;

Tip

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

一部の例では、 toJSON()関数を使用して、 BSONドキュメントである変更イベントを拡張JSONとして表します。この関数を使用するには、次のコードをアプリケーションファイルに貼り付けます。

function toJSON(object $document): string
{
    return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON();
}

変更ストリームを開く

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

MongoDB\Client: MongoDBデプロイのすべての変更を監視
MongoDB\Database:データベース内のすべてのコレクションの変更を監視
MongoDB\Collection:コレクションの変更を監視

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

$changeStream = $collection->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {
        break;
    }
}

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

$result = $collection->updateOne(
    ['name' => 'Blarney Castle'],
    ['$set' => ['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" : [  ] } }

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

変更ストリーム出力を変更するには、配列内のパイプラインステージをwatch()メソッドのパラメーターとして渡します。配列には、次のステージを含めることができます。

$addFields または$set : ドキュメントに新しいフィールドを追加します
$match: ドキュメントをフィルタリングします
$project:ドキュメントフィールドのサブセットをプロジェクションします
$replaceWith または$replaceRoot : 入力ドキュメントを指定されたドキュメントで置き換え
$redact: ドキュメントのコンテンツを制限します
$unset: ドキュメントからフィールドを削除します

次の例では、 $matchステージを含むパイプラインをwatch()メソッドに渡します。これは、アップデート操作が発生した場合にのみイベントを出力するようにwatch()メソッドに指示します。

$pipeline = [['$match' => ['operationType' => 'update']]];
$changeStream = $collection->watch($pipeline);
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {
        break;
    }
}

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

watch()メソッドの動作を変更するには、オプション配列をパラメーターとしてwatch()に渡します。次の表では、配列に設定できる便利なオプションについて説明しています。

オプション	説明
`fullDocument`	Specifies whether to show the full document after the change, rather than showing only the changes made to the document. To learn more about this option, see the Include Pre-Images and Post-Images section of this guide.
`fullDocumentBeforeChange`	Specifies whether to show the full document as it was before the change, rather than showing only the changes made to the document. To learn more about this option, see Include Pre-Images and Post-Images.
`startAfter`	Instructs `watch()` to start a new change stream after the operation specified in the resume token. This field allows notifications to resume after an invalidate event. Each change stream event document includes a resume token as the `_id` field. Pass the entire `_id` field of the change event document that represents the operation you want to resume after. This option is mutually exclusive with `resumeAfter` and `startAtOperationTime`.
`startAtOperationTime`	Instructs the change stream to only provide changes that occurred at or after the specified timestamp. This option is mutually exclusive with `startAfter` and `resumeAfter`.
`collation`	Sets the collation to use for the change stream cursor.

watch()オプションの完全なリストについては、 APIドキュメントのMongoDB $ Collection::watch()を参照してください。

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

重要

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

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

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

MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE: 変更イベントには、変更イベント用に変更されたドキュメントの変更前のイメージが含まれます。変更前のイメージが利用できない場合、この変更イベントフィールドの値はnullになります。
MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED: 変更イベントには、変更イベント用に変更されたドキュメントの変更前のイメージが含まれます。変更前のイメージが利用できない場合、サーバーはエラーを発生させます。

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

MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP: 変更イベントには、変更後一定時間の変更されたドキュメント全体のコピーが含まれます。
MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE: 変更イベントには、変更イベントの変更されたドキュメントの変更後のイメージが含まれます。変更後イメージが利用できない場合、この変更イベントフィールドの値はnullになります。
MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED: 変更イベントには、変更イベントの変更されたドキュメントの変更後のイメージが含まれます。変更後のイメージが利用できない場合、サーバーはエラーを発生させます。

次の例では、コレクションでwatch()メソッドを呼び出し、 fullDocumentオプションを設定して更新されたドキュメントの変更後のイメージを含めます。

$options = ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP];
$changeStream = $collection->watch([], $options);
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    echo toJSON($event), PHP_EOL;
    if ($event['operationType'] === 'invalidate') {
        break;
    }
}

別shellで実行中されている変更ストリームアプリケーションでは、前述の更新例を使用して 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 ドキュメントを参照してください。

戻る

個別のフィールド値

Write Data