Cloud Functions は、その関数と同じ Cloud プロジェクトの Cloud Firestore 内のイベントを処理できます。Firestore API とクライアント ライブラリを使用すると、これらのイベントの発生時に Cloud Firestore の読み取りや更新を行うことができます。
一般的なライフサイクルの場合、Cloud Firestore の関数は次のように動作します。
特定のドキュメントに変更が加えられるのを待ちます。
イベントが発生するとトリガーされ、そのタスクを実行します。
影響を受けるドキュメントのスナップショットを含むデータ オブジェクトを受信します。
write
またはupdate
イベントの場合、トリガー イベントの前後のドキュメントの状態を表すスナップショットがデータ オブジェクトに含まれます。
イベントタイプ
Cloud Firestore は、create
、update
、delete
、write
イベントをサポートします。write
イベントには、ドキュメントに対するすべての変更が含まれます。
イベントタイプ | トリガー |
---|---|
providers/cloud.firestore/eventTypes/document.create (デフォルト) |
ドキュメントが最初に書き込まれたときにトリガーされます。 |
providers/cloud.firestore/eventTypes/document.update |
すでに存在するドキュメントの値が変更されたときにトリガーされます。 |
providers/cloud.firestore/eventTypes/document.delete |
データを含むドキュメントが削除されたときにトリガーされます。 |
providers/cloud.firestore/eventTypes/document.write |
ドキュメントが作成、更新、削除されたときにトリガーされます。 |
ワイルドカードは、次のように中括弧で記述します。
"/projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}"
ドキュメント パスの指定
関数をトリガーするには、リッスンするドキュメント パスを指定します。関数はドキュメントの変更にのみ対応します。特定のフィールドやコレクションはモニタリングできません。有効なドキュメント パスは次のとおりです。
users/marie
: 有効なトリガー。1 つのドキュメント(/users/marie
)をモニタリングします。users/{username}
: 有効なトリガー。すべてのユーザー ドキュメントをモニタリングします。コレクション内のすべてのドキュメントをモニタリングする場合は、ワイルドカードを使用します。users/{username}/addresses
: 無効なトリガー。ドキュメントではなく、サブコレクションaddresses
を参照します。users/{username}/addresses/home
: 有効なトリガー。すべてのユーザーの自宅住所のドキュメントをモニタリングします。users/{username}/addresses/{addressId}
: 有効なトリガー。すべての住所ドキュメントをモニタリングします。
ワイルドカードとパラメータの使用
モニタリングするドキュメントがわからない場合は、ドキュメント ID の代わりに {wildcard}
を使用します。
users/{username}
は、すべてのユーザー ドキュメントに対する変更をリッスンします。
この例では、users
にあるドキュメントの任意のフィールドが変更されると、{username}
というワイルドカードと照合されます。
users
のドキュメントにサブコレクションがあり、サブコレクションのいずれかのドキュメントのフィールドが変更された場合、{username}
ワイルドカードはトリガーされません。
ワイルドカードに一致した部分が、ドキュメント パスから抽出されます。明示的なコレクションまたはドキュメント ID に置き換えるワイルドカードは、必要な数だけ定義できます。
イベントの構造
このトリガーは、次のようなイベントで関数を呼び出します。
{ "oldValue": { // Update and Delete operations only A Document object containing a pre-operation document snapshot }, "updateMask": { // Update operations only A DocumentMask object that lists changed fields. }, "value": { // A Document object containing a post-operation document snapshot } }
それぞれの Document
オブジェクトに 1 つまたは複数の Value
オブジェクトが含まれます。型の詳細については、Value
ドキュメントをご覧ください。これは、Go などの型言語を使用して関数を記述する場合に便利です。
コードサンプル
以下の Cloud Functions の関数のサンプルでは、トリガーする Cloud Firestore イベントのフィールドを出力します。
Node.js
Python
Go
Java
C#
Ruby
次の例では、ユーザーが追加した値を取得し、その場所にある文字列を大文字に変換して、値を大文字の文字列に置き換えています。
Node.js
Python
Go
Java
C#
関数のデプロイ
次の gcloud
コマンドは、ドキュメント /messages/{pushId}
に対する書き込みイベントによってトリガーされる関数をデプロイします。
gcloud functions deploy FUNCTION_NAME \ --runtime RUNTIME \ --trigger-event "providers/cloud.firestore/eventTypes/document.write" \ --trigger-resource "projects/YOUR_PROJECT_ID/databases/(default)/documents/messages/{pushId}"
引数 | 説明 |
---|---|
--runtime RUNTIME |
使用しているランタイムの名前。網羅的なリストについては、gcloud リファレンスをご覧ください。 |
--trigger-event NAME |
関数がモニタリングするイベントタイプ(write 、create 、update または delete )。 |
--trigger-resource NAME |
関数がリッスンするデータベース パスの完全修飾名。次の形式に従う必要があります。
"projects/YOUR_PROJECT_ID/databases/(default)/documents/PATH"
{pushId} テキストは、ドキュメント パスの指定で説明したワイルドカード パラメータです。 |
制約と保証
Cloud Functions 用 Firestore トリガーはベータ版の機能であり、いくつかの既知の制限があります。
- 関数が Firestore の変更に応答するまで最大 10 秒かかることがあります。
- 順序は保証されません。短時間に複数の変更を行うと、予期しない順序で関数がトリガーされることがあります。
- イベントは必ず 1 回以上処理されますが、1 つのイベントで関数が複数回呼び出される場合があります。「正確に 1 回」のメカニズムに依存することは避け、べき等になるように関数を記述してください。
- Cloud Functions 用 Firestore トリガーは、ネイティブ モードの Firestore でのみ使用できます。Datastore モードの Firestore では使用できません。