Cloud Functions(第 2 世代)で拡張する
Cloud Functions を使用してコードをデプロイすることで、Firestore データベースの変更によってトリガーされるイベントを処理できます。これにより、独自のサーバーを実行しなくても、サーバー側の機能を追加できます。
Cloud Functions(第 2 世代)を使用して Firestore を拡張する
Cloud Functions(第 2 世代)では、次の Firestore イベント トリガーをサポートして、Firestore イベントに関連付けられたハンドラを作成できます。
イベントタイプ | トリガー |
---|---|
google.cloud.firestore.document.v1.created |
ドキュメントが最初に書き込まれたときにトリガーされます。 |
google.cloud.firestore.document.v1.updated |
すでに存在するドキュメントの値が変更されたときにトリガーされます。 |
google.cloud.firestore.document.v1.deleted |
ドキュメントが削除されたときにトリガーされます。 |
google.cloud.firestore.document.v1.written |
created 、updated または deleted がトリガーされたときにトリガーされます。 |
google.cloud.firestore.document.v1.created.withAuthContext |
created と同じですが、認証情報を追加します。 |
google.cloud.firestore.document.v1.updated.withAuthContext |
updated と同じですが、認証情報を追加します。 |
google.cloud.firestore.document.v1.deleted.withAuthContext |
deleted と同じですが、認証情報を追加します。 |
google.cloud.firestore.document.v1.written.withAuthContext |
written と同じですが、認証情報を追加します。 |
Firestore のイベントは、ドキュメントが変更された場合にのみトリガーされます。Firestore ドキュメントの更新でデータが変更されない場合(オペレーションなしの書き込み)、更新イベントや書き込みイベントは生成されません。特定のフィールドにイベントを追加することはできません。
イベントに認証コンテキストを含める
イベントに関する追加の認証情報を含めるには、withAuthContext
拡張機能とともにイベント トリガーを使用します。この拡張機能は、イベントをトリガーしたプリンシパルに関する追加情報を追加します。ベースイベントで返される情報に加えて、authtype
属性と authid
属性を追加します。属性値の詳細については、authcontext
のリファレンスをご覧ください。
Firestore でトリガーされる関数を作成する
Firestore イベントに応答する関数を作成するには、デプロイ中に次の内容を指定する準備を行います。
- トリガー イベントのタイプ
- 関数に関連付けられたドキュメントを選択するトリガー イベント フィルタ
- 実行する関数コード
トリガー イベント フィルタ
イベント フィルタを指定するときに、ドキュメントの完全一致またはパスパターンを指定できます。パスパターンを使用して、ワイルドカード *
または **
を使用して複数のドキュメントに一致させます。
たとえば、次のドキュメントへの変更に応答できます。
users/marie
パターンに一致するドキュメントの変更に対応するには、ワイルドカード *
または **
を使用します。ワイルドカード *
は単一のセグメントに一致し、マルチセグメント ワイルドカード **
はパターン内の 0 個以上のセグメントに一致します。
単一セグメントの一致(*
)の場合は、名前付きキャプチャ グループを使用することもできます。例: users/{userId}
例:
パターン | 説明 |
---|---|
/users/* または /users/{userId} |
/users コレクション内のすべてのドキュメントに一致します。/users/marie/messages/33e2IxYBD9enzS50SJ68 のようなサブコレクションのドキュメントと一致しません |
/users/** |
/users コレクション内のすべてのドキュメントと、/users/marie/messages/33e2IxYBD9enzS50SJ68 などのサブコレクションのドキュメントと一致します。 |
パスパターンの詳細については、Eventarc パスのパターンをご覧ください。
ワイルドカードを使用する場合でも、トリガーは常にドキュメントを指している必要があります。たとえば、{messageCollectionId=*}
はコレクションであるため、users/{userId=*}/{messageCollectionId=*}
は無効になります。一方で、{messageId=*}
は常にドキュメントを指すため、users/{userId=*}/{messageCollectionId}/{messageId=*}
は有効です。
関数の例
次のサンプルは、Firestore イベントを受信する方法を示しています。イベントに関連するドキュメント データを操作するには、value
フィールドと old_value
フィールドを確認します。
value
: オペレーション後のドキュメント スナップショットを含むDocument
オブジェクト。このフィールドは、削除イベントについては入力されません。old_value
: オペレーション前のドキュメント スナップショットを含むDocument
オブジェクト。このフィールドは、更新イベントと削除イベントに対してのみ入力されます。
Go
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
protobufjs を使用してイベントデータをデコードします。ソースにgoogle.events.cloud.firestore.v1
data.proto
を含めます。
Python
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
C#
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
次の例では、影響を受けるドキュメントの original
フィールドに追加された文字列を大文字に変換し、新しい値を同じドキュメントに書き込みます。
Go
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Node.js
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
protobufjs を使用してイベントデータをデコードします。ソースにgoogle.events.cloud.firestore.v1
data.proto
を含めます。
Python
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
C#
Firestore に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
proto 依存関係をソースに含める
関数のソース ディレクトリに Firestore data.proto
ファイルを含める必要があります。このファイルは、ソース ディレクトリにも含める必要がある次の proto をインポートします。
依存関係に同じディレクトリ構造を使用します。たとえば、struct.proto
は google/protobuf
内に配置します。
これらのファイルは、イベントデータをデコードするのに必要です。関数のソースにこれらのファイルが含まれていない場合は、実行時にエラーが返されます。
イベント属性
各イベントには、イベントがトリガーされた時間など、イベントに関する情報を含むデータ属性が含まれます。Firestore は、イベントに関連するデータベースとドキュメントに関するデータを追加します。これらの属性には、次のようにアクセスできます。
Java
logger.info("Function triggered by event on: " + event.getSource()); logger.info("Event type: " + event.getType()); logger.info("Event time " + event.getTime()); logger.info("Event project: " + event.getExtension("project")); logger.info("Event location: " + event.getExtension("location")); logger.info("Database name: " + event.getExtension("database")); logger.info("Database document: " + event.getExtension("document")); // For withAuthContext events logger.info("Auth information: " + event.getExtension("authid")); logger.info("Auth information: " + event.getExtension("authtype"));
Node.js
console.log(`Function triggered by event on: ${cloudEvent.source}`); console.log(`Event type: ${cloudEvent.type}`); console.log(`Event time: ${cloudEvent.time}`); console.log(`Event project: ${cloudEvent.project}`); console.log(`Event location: ${cloudEvent.location}`); console.log(`Database name: ${cloudEvent.database}`); console.log(`Document name: ${cloudEvent.document}`); // For withAuthContext events console.log(`Auth information: ${cloudEvent.authid}`); console.log(`Auth information: ${cloudEvent.authtype}`);
Python
print(f"Function triggered by change to: {cloud_event['source']}") print(f"Event type: {cloud_event['type']}") print(f"Event time: {cloud_event['time']}") print(f"Event project: {cloud_event['project']}") print(f"Location: {cloud_event['location']}") print(f"Database name: {cloud_event['database']}") print(f"Document: {cloud_event['document']}") // For withAuthContext events print(f"Auth information: {cloud_event['authid']}") print(f"Auth information: {cloud_event['authtype']}")
関数をデプロイする
Cloud Functions の関数をデプロイするユーザーには、Cloud Functions デベロッパーの IAM ロールまたは同等の権限を含むロールが必要です。デプロイの追加構成もご覧ください。
関数をデプロイするには、gcloud CLI または Google Cloud コンソールを使用します。以下の例は、gcloud CLI を使用したデプロイを示しています。Google Cloud コンソールを使用したデプロイの詳細については、Cloud Functions をデプロイするをご覧ください。
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
gcloud functions deploy
コマンドを使用して、関数をデプロイします。gcloud functions deploy YOUR_FUNCTION_NAME \ --gen2 \ --region=FUNCTION_LOCATION \ --trigger-location=TRIGGER_LOCATION \ --runtime=YOUR_RUNTIME \ --source=YOUR_SOURCE_LOCATION \ --entry-point=YOUR_CODE_ENTRYPOINT \ --trigger-event-filters="type=EVENT_FILTER_TYPE" \ --trigger-event-filters="database=DATABASE" \ --trigger-event-filters-path-pattern="document=DOCUMENT" \
最初の引数
YOUR_FUNCTION_NAME
は、デプロイされた関数の名前です。関数名は、先頭を文字にし、その後に 62 文字以下の文字、数字、ハイフン、アンダースコアを続けます。末尾は文字または数字にする必要があります。--gen2
フラグは、Cloud Functions(第 2 世代)にデプロイすることを指定します。このフラグを省略すると、Cloud Functions(第 1 世代)にデプロイされます。--region
フラグには、関数をデプロイするリージョンを指定します。近接性を最大化するには、Firestore データベースの近くのリージョンに設定します。Firestore データベースがマルチリージョン ロケーションにある場合、
nam5
のデータベースの場合はus-central1
に、eur3
のデータベースの場合はeurope-west4
に設定します。リージョン Firestore のロケーションの場合は、同じリージョンに設定します。--trigger-location
フラグには、トリガーのロケーションを指定します。このフラグを Firestore データベースのロケーションに設定する必要があります。--runtime
フラグには、関数で使用される言語ランタイムを指定します。Cloud Functions は、複数のランタイムをサポートしています。詳細については、ランタイムをご覧ください。--source
フラグには、関数のソースコードの場所を指定します。詳細については、以下をご覧ください。--entry-point
フラグには、ソースコード内の関数のエントリ ポイントを指定します。これは、関数の実行時に実行されるコードです。このフラグには、ソースコード内に存在する関数名または完全修飾クラス名を指定する必要があります。詳細については、関数のエントリ ポイントをご覧ください。EVENT_FILTER_TYPE
: Firestore は、次のイベントタイプをサポートしています。google.cloud.firestore.document.v1.created
: ドキュメントが最初に書き込まれたときにイベントが送信されます。google.cloud.firestore.document.v1.updated
: ドキュメントがすでに存在し、値が変更されたときに、イベントが送信されます。google.cloud.firestore.document.v1.deleted
: ドキュメントが削除されたときにイベントが送信されます。google.cloud.firestore.document.v1.written
: ドキュメントが作成、更新、または削除されたときにイベントが送信されます。google.cloud.firestore.document.v1.created.withAuthContext
: ドキュメントが最初に書き込まれたときにイベントが送信されます。このイベントには追加の認証情報が含まれています。google.cloud.firestore.document.v1.updated.withAuthContext
: ドキュメントがすでに存在し、値が変更されたときに、イベントが送信されます。追加の認証情報が含まれていますgoogle.cloud.firestore.document.v1.deleted.withAuthContext
: ドキュメントが削除されたときにイベントが送信されます。追加の認証情報が含まれていますgoogle.cloud.firestore.document.v1.written.withAuthContext
: ドキュメントが作成、更新、または削除されたときにイベントが送信されます。追加の認証情報が含まれています
DATABASE
: Firestore データベース。デフォルトのデータベース名には、(default)
を使用します。DOCUMENT
: データが作成、更新、削除されたときにイベントをトリガーするデータベース パス。演算子には次のいずれかを指定できます。- 等しい。例:
--trigger-event-filters=document='users/marie'
- 経路パターン。例:
--trigger-event-filters-path-pattern=document='users/*'
詳細については、パスパターンについてをご覧ください。
- 等しい。例:
関数をデプロイするときに、追加の構成、ネットワーキング、セキュリティのオプションを指定することもできます。
デプロイ コマンドとそのフラグの詳細については、
gcloud functions deploy
のドキュメントをご覧ください。
デプロイの例
次の例は、Google Cloud CLI を使用したデプロイを示しています。
us-west2
リージョンにデータベースの関数をデプロイします。
gcloud functions deploy gcfv2-trigger-firestore-node \
--gen2 \
--region=us-west2 \
--trigger-location=us-west2 \
--runtime=nodejs18 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=makeUpperCase \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
nam5
マルチリージョンにデータベースの関数をデプロイします。
gcloud functions deploy gcfv2-trigger-firestore-python \
--gen2 \
--region=us-central1 \
--trigger-location=nam5 \
--runtime=python311 \
--source=gs://CLOUD_STORAGE_BUCKET/firestoreEventFunction.zip \
--entry-point=make_upper_case \
--trigger-event-filters=type=google.cloud.firestore.document.v1.written.withAuthContext \
--trigger-event-filters=database='(default)' \
--trigger-event-filters-path-pattern=document='messages/{pushId}'
制限事項
Cloud Functions の Firestore トリガーには、次の制限事項があります。
- Cloud Functions(第 1 世代)では、Firestore ネイティブ モードの既存の「(デフォルト)」データベースがあることが前提となります。Firestore の名前付きデータベースや Datastore モードはサポートされていません。これらを使用している場合にイベントを構成するには、Cloud Functions(第 2 世代)を使用してください。
- 順序は保証されません。短時間に複数の変更を行うと、予期しない順序で関数の呼び出しがトリガーされることがあります。
- イベントは必ず 1 回以上処理されますが、1 つのイベントで関数が複数回呼び出される場合があります。「正確に 1 回」のメカニズムに依存することは避け、べき等性がある関数を記述してください。
- Datastore モードの Firestore には、Cloud Functions(第 2 世代)が必要です。Cloud Functions(第 1 世代)では、Datastore モードはサポートされていません。
- トリガーは、単一のデータベースに関連付けられます。複数のデータベースに一致するトリガーは作成できません。
- データベースを削除しても、そのデータベースのトリガーは自動的に削除されません。トリガーはイベントの配信を停止しますが、トリガーを削除するまで存在し続けます。
- 一致したイベントが最大リクエスト サイズを超えると、イベントが Cloud Functions(第 1 世代)に配信されない場合があります。
- リクエスト サイズが原因で配信されなかったイベントは、プラットフォーム ログに記録され、プロジェクトのログ使用量にカウントされます。
- これらのログは、ログ エクスプローラで「サイズが第 1 世代の上限を超えているため、イベントを Cloud Functions に配信できません...」という
error
重大度メッセージとともに表示されます。関数名はfunctionName
フィールドで確認できます。receiveTimestamp
フィールドが現在から 1 時間以内であれば、タイムスタンプの前後のスナップショットで問題のドキュメントを読み取ることで、実際のイベントの内容を推測できます。 - このようなケイデンスを回避するには、次のようにします。
- Cloud Functions(第 2 世代)に移行してアップグレードする
- ドキュメントのサイズを縮小する
- 問題の Cloud Functions を削除する
- 除外を使用してロギング自体を無効にすることもできますが、問題のあるイベントは配信されないことに注意してください。
Eventarc と Firestore のロケーション
Eventarc は、Firestore イベント トリガーのマルチリージョンをサポートしていませんが、マルチリージョン ロケーションの Firestore データベースのトリガーは作成できます。Eventarc は、Firestore マルチリージョン ロケーションを次の Eventarc リージョンにマッピングします。
Firestore マルチリージョン | Eventarc リージョン |
---|---|
nam5 |
us-central1 |
eur3 |
europe-west4 |
Cloud Functions の第 2 世代と第 1 世代の違い
Cloud Functions(第 2 世代)では、すべてのランタイムに Eventarc イベントを使用します。以前は、Cloud Functions(第 1 世代)では、一部のランタイムのみに Eventarc イベントが使用されていました。Eventarc イベントでは、Cloud Functions(第 1 世代)と次の点が異なります。
Eventarc 用の Firestore トリガーは、Cloud Functions 以外の追加の宛先をサポートしています。
CloudEvents
は、Cloud Run、GKE、Workflows など、さまざまな宛先に転送できます。Eventarc の Firestore トリガーは、データベース書き込みオペレーションの開始時にトリガー定義を取得し、その定義を使用して Firestore がイベントを出力するかどうかを判断します。書き込みオペレーションでは、実行時に発生する可能性のある定義の変更を考慮することはありません。
Cloud Functions(第 1 世代)は、データベース書き込みの評価中にトリガー定義を取得し、評価中のトリガーの変更は、Firestore がイベントを出力するかどうかに影響します。
詳細については、Cloud Functions のバージョンの比較をご覧ください。