Firestore でトリガーを作成する

このガイドでは、Firestore イベントから Cloud Run サービスと関数のトリガーを作成する手順について説明します。

Firestore データベース内のイベントによってトリガーされるように Cloud Run サービスを構成できます。トリガーされると、サービスは Firestore API とクライアント ライブラリを介して、これらのイベントに応答して Firestore データベースを読み取り、更新します。

一般的なライフサイクルでは、Firestore イベントによって Cloud Run サービスがトリガーされると、次のように処理されます。

  1. サービスは、特定のドキュメントに変更が加えられるのを待ちます。

  2. 変更が発生すると、サービスがトリガーされ、タスクを実行します。

  3. サービスは、影響を受けるドキュメントのスナップショットを含むデータ オブジェクトを受信します。write イベントまたは update イベントの場合、トリガー イベントの前後のドキュメントの状態を表すスナップショットがデータ オブジェクトに含まれます。

イベントタイプ

Firestore は、create、update、delete、write イベントをサポートしています。write イベントには、ドキュメントに対するすべての変更が含まれます。

イベントタイプ トリガー
google.cloud.firestore.document.v1.created（デフォルト） ドキュメントが最初に書き込まれたときにトリガーされます。
google.cloud.firestore.document.v1.updated すでに存在するドキュメントの値が変更されたときにトリガーされます。
google.cloud.firestore.document.v1.deleted データを含むドキュメントが削除されたときにトリガーされます。
google.cloud.firestore.document.v1.written ドキュメントが作成、更新、削除されたときにトリガーされます。

ワイルドカードは、次のように中括弧で記述します。 projects/YOUR_PROJECT_ID/databases/(default)/documents/collection/{document_wildcard}

ドキュメントのパスを指定する

サービスをトリガーするには、リッスンするドキュメント パスを指定します。ドキュメント パスは、サービスと同じ Google Cloud プロジェクトに存在する必要があります。

有効なドキュメント パスは次のとおりです。

  • users/marie: 有効なトリガー。1 つのドキュメント（/users/marie）をモニタリングします。

  • users/{username}: 有効なトリガー。すべてのユーザー ドキュメントをモニタリングします。コレクション内のすべてのドキュメントをモニタリングする場合は、ワイルドカードを使用します。

  • users/{username}/addresses: 無効なトリガー。ドキュメントではなく、サブコレクション addresses を参照します。

  • users/{username}/addresses/home: 有効なトリガー。すべてのユーザーの自宅住所のドキュメントをモニタリングします。

  • users/{username}/addresses/{addressId}: 有効なトリガー。すべての住所ドキュメントをモニタリングします。

  • users/{user=**}: 有効なトリガー。すべてのユーザー ドキュメントと、各ユーザー ドキュメントのサブコレクション（/users/userID/address/home や /users/userID/phone/work など）内のドキュメントをモニタリングします。

ワイルドカードとパラメータ

モニタリングするドキュメントが不明な場合は、ドキュメント ID の代わりに {wildcard} を使用します。

  • users/{username} は、すべてのユーザー ドキュメントに対する変更をリッスンします。

この例では、users にあるドキュメントの任意のフィールドが変更されると、{username} というワイルドカードと照合されます。

users に含まれるドキュメントにサブコレクションがある場合、サブコレクションのいずれかに含まれるドキュメントのフィールドが変更されても、{username} ワイルドカードはトリガーされません。サブコレクション内のイベントにも応答することが目標なら、マルチセグメント ワイルドカード {username=**} を使用します。

ワイルドカードに一致した部分が、ドキュメント パスから抽出されます。明示的なコレクションまたはドキュメント ID に置き換えるワイルドカードは、必要な数だけ定義できます。最大 1 つのマルチセグメント ワイルドカード（{username=**} など）を使用できます。

イベントの構造

このトリガーは、次のようなイベントでサービスを呼び出します。

{
    "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 ドキュメントをご覧ください。

始める前に

  1. 設定ページの説明に従って、Cloud Run に新しいプロジェクトを設定したことを確認してください。

  2. Artifact Registry、Cloud Build、Cloud Run Admin API、Eventarc、Firestore Cloud Logging、Pub/Sub API を有効にします。

    API を有効にする

必要なロール

  1. プロジェクト作成者には、オーナーロール（roles/owner）が付与されます。デフォルトでは、この Identity and Access Management（IAM）ロールには、ほとんどの Google Cloud リソースへの完全アクセス権に必要な権限が含まれており、この手順は省略できます。

    プロジェクト作成者でない場合は、プロジェクトで適切なプリンシパルに必要な権限を付与する必要があります。プリンシパルは Google アカウント（エンドユーザーの場合）やサービス アカウント（アプリケーションとコンピューティング ワークロードの場合）になることもあります。詳細については、イベントの宛先のロールと権限のページをご覧ください。

    デフォルトでは、Cloud Build の権限には、Artifact Registry アーティファクトをアップロードおよびダウンロードするための権限が含まれています。

    必要な権限

    Firestore トリガーの構成に必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

    ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

    必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

  2. Compute Engine のデフォルトのサービス アカウントをメモしておいてください。テスト目的で、Eventarc トリガーに関連付けて、トリガーの ID を示すためです。このサービス アカウントは、Compute Engine を使用する Google Cloud サービスを有効にするか、使用すると自動的に作成されます。メールアドレスの形式は次のとおりです。

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    PROJECT_NUMBER は、実際の Google Cloud プロジェクトの番号に置き換えます。プロジェクト番号は、Google Cloud コンソールの [ようこそ] ページで確認できます。また、次のコマンドで確認することもできます。

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    本番環境では、新しいサービス アカウントを作成して、必要最小限の権限を含む、最小権限の原則に従った 1 つ以上の IAM ロールを付与することを強くおすすめします。

  3. デフォルトでは、Cloud Run サービスを呼び出すことができるのは、プロジェクト オーナー、プロジェクト編集者、Cloud Run 管理者、起動元のみです。サービスごとにアクセスを制御できます。ただし、テスト目的の場合は、Google Cloud プロジェクトの Cloud Run 起動元ロール（run.invoker）を Compute Engine サービス アカウントに付与してください。これにより、プロジェクト内のすべての Cloud Run サービスとジョブにロールが付与されます。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Cloud Run 起動元ロールを付与せずに認証済みの Cloud Run サービスのトリガーを作成すると、トリガーは正常に作成され、アクティブになります。ただし、トリガーが期待どおりに機能せず、次のようなメッセージがログに記録されます。

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. プロジェクトの Eventarc イベント レシーバーのロール（roles/eventarc.eventReceiver）を Compute Engine のデフォルト サービス アカウントに付与して、Eventarc トリガーがイベント プロバイダからイベントを受信できるようにします。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. 2021 年 4 月 8 日以前に、認証済みの Pub/Sub push リクエストをサポートするために Cloud Pub/Sub サービス エージェントを有効にした場合は、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）をサービス エージェントに付与します。それ以外の場合、このロールはデフォルトで付与されます。
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Firestore データベースを設定する

サービスをデプロイする前に、Firestore データベースを作成する必要があります。

  1. Firestore の [データ] ページに移動します。

  2. [データベースを作成] を選択します。

  3. [ネイティブ モード] をクリックし、[続行] を選択します。

  4. [データベースに名前を付ける] フィールドに、データベース ID（firestore-db など）を入力します。

  5. [ロケーション タイプ] で [リージョン] を選択し、データベースを配置するリージョンを選択します。この選択は永続的に適用されます。

  6. [Secure rules] セクションはそのままにします。

  7. [データベースを作成] をクリックします。

Firestore データモデルは、ドキュメントを含むコレクションで構成されます。ドキュメントには、一連の Key-Value ペアが含まれています。

トリガーを作成する

デプロイするサービスのタイプに応じて、次のいずれかを行います。

サービスのトリガーを作成する

トリガーは、サービスをデプロイした後に指定できます。

任意のツールを使用して、手順のタブでクリックします。

コンソール

  1. コンテナを使用するか、ソースから Cloud Run サービスをデプロイします。

  2. Google Cloud コンソールで、[Cloud Run] に移動します。

    [Cloud Run] に移動

  3. サービスのリストで既存のサービスをクリックします。

  4. サービスの詳細ページで、[トリガー] タブに移動します。

  5. [トリガーを追加] をクリックし、[Firestore トリガー] を選択します。

  6. [Eventarc トリガー] ペインで、トリガーの詳細を次のように変更します。

    1. [トリガー名] フィールドにトリガーの名前を入力するか、デフォルトの名前を使用します。

    2. リストからトリガーのタイプを選択して、次のいずれかのトリガータイプを指定します。

      • Google のソース: Pub/Sub、Cloud Storage、Firestore などの Google イベント プロバイダのトリガーを指定できます。

      • サードパーティ: Eventarc ソースを提供する Google 以外のプロバイダと統合できます。詳細については、Eventarc のサードパーティ イベントをご覧ください。

    3. [イベント プロバイダ] リストから [Firestore] を選択し、サービスをトリガーするイベントのタイプを提供するプロダクトを選択します。イベント プロバイダのリストについては、イベント プロバイダと宛先をご覧ください。

    4. [イベントタイプ] リストから [type=google.cloud.firestore.document.v1.created] を選択します。トリガーの構成は、サポートされているイベントタイプによって異なります。詳細については、イベントタイプをご覧ください。

    5. [フィルタ] セクションで、データベース、オペレーション、属性の値を選択するか、デフォルト値を使用します。

    6. [リージョン] フィールドが有効になっている場合は、Eventarc トリガーのロケーションを選択します。一般に、Eventarc トリガーのロケーションは、イベントをモニタリングする Google Cloud リソースのロケーションと一致する必要があります。ほとんどの場合、サービスも同じリージョンにデプロイする必要があります。Eventarc トリガーのロケーションの詳細については、Eventarc のロケーションについてをご覧ください。

    7. [サービス アカウント] フィールドで、サービス アカウントを選択します。Eventarc トリガーはサービス アカウントにリンクされ、サービスを呼び出すときに ID として使用します。Eventarc トリガーのサービス アカウントには、サービスを呼び出す権限が必要です。デフォルトでは、Cloud Run は Compute Engine のデフォルトのサービス アカウントを使用します。

    8. 受信リクエストの送信先であるサービスの URL パスを指定することもできます。これは、トリガーのイベントの送信先である宛先サービスの相対パスです。例: /、/route、route、route/subroute.

    9. 必須フィールドに値を入力したら、[トリガーを保存] をクリックします。

  7. トリガーの作成後、[トリガー] タブにチェックマーク が付いていることを確認します。

gcloud

  1. コンテナを使用するか、ソースから Cloud Run サービスをデプロイします。

  2. 次のコマンドを実行して、イベントをフィルタするトリガーを作成します。

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    次のように置き換えます。

    • TRIGGER_NAME: トリガーの名前。

    • EVENTARC_TRIGGER_LOCATION: Eventarc トリガーのロケーション。一般に、Eventarc トリガーのロケーションは、イベントをモニタリングする Google Cloud リソースのロケーションと一致する必要があります。ほとんどの場合、サービスも同じリージョンにデプロイする必要があります。詳細については、Eventarc のロケーションをご覧ください。

    • SERVICE は、デプロイするサービスの名前に置き換えます。

    • REGION は、サービスの Cloud Run リージョンに置き換えます。

    • PROJECT_NUMBER は、Google Cloud プロジェクト番号に置き換えます。Eventarc トリガーはサービス アカウントにリンクされ、サービスを呼び出すときに ID として使用します。Eventarc トリガーのサービス アカウントには、サービスを呼び出す権限が必要です。デフォルトでは、Cloud Run はデフォルトのコンピューティング サービス アカウントを使用します。

    • event-filters フラグには、トリガーがモニタリングするイベント フィルタを指定します。event-filters フィルタにすべて一致するイベントが、サービスの呼び出しをトリガーします。各トリガーには、サポートされているイベントタイプを指定する必要があります。作成後にイベント フィルタのタイプを変更することはできません。イベント フィルタのタイプを変更するには、新しいトリガーを作成して古いトリガーを削除する必要があります。（省略可）さらにフィルタを追加するには、--event-filters フラグを繰り返し、サポートされているフィルタを ATTRIBUTE=VALUE の形式で指定します。

関数のトリガーを作成する

任意のツールを使用して、手順のタブでクリックします。

コンソール

Google Cloud コンソールを使用して関数を作成するときに、関数にトリガーを追加することもできます。関数のトリガーを作成する手順は次のとおりです。

  1. Google Cloud コンソールで、[Cloud Run] に移動します。

    Cloud Run に移動します。

  2. [関数を作成] をクリックし、関数の詳細を入力します。デプロイ時に関数を構成する方法については、関数をデプロイするをご覧ください。

  3. [トリガー] セクションで [トリガーを追加] をクリックします。

  4. [Firestore トリガー] を選択します。

  5. [Eventarc トリガー] ペインで、トリガーの詳細を次のように変更します。

    1. [トリガー名] フィールドにトリガーの名前を入力するか、デフォルトの名前を使用します。

    2. リストからトリガーのタイプを選択して、次のいずれかのトリガータイプを指定します。

      • Google のソース: Pub/Sub、Cloud Storage、Firestore などの Google イベント プロバイダのトリガーを指定できます。

      • サードパーティ: Eventarc ソースを提供する Google 以外のプロバイダと統合できます。詳細については、Eventarc のサードパーティ イベントをご覧ください。

    3. [イベント プロバイダ] リストから [Firestore] を選択し、関数をトリガーするイベントのタイプを提供するプロダクトを選択します。イベント プロバイダのリストについては、イベント プロバイダと宛先をご覧ください。

    4. [イベントタイプ] リストから [type=google.cloud.firestore.document.v1.created] を選択します。トリガーの構成は、サポートされているイベントタイプによって異なります。詳細については、イベントタイプをご覧ください。

    5. [フィルタ] セクションで、データベース、オペレーション、属性の値を選択するか、デフォルト値を使用します。

    6. [リージョン] フィールドが有効になっている場合は、Eventarc トリガーのロケーションを選択します。一般に、Eventarc トリガーのロケーションは、イベントをモニタリングする Google Cloud リソースのロケーションと一致する必要があります。ほとんどの場合、Cloud Functions の関数を同じリージョンにデプロイする必要があります。Eventarc トリガーのロケーションの詳細については、Eventarc のロケーションについてをご覧ください。

    7. [サービス アカウント] フィールドで、サービス アカウントを選択します。Eventarc トリガーはサービス アカウントにリンクされ、関数を呼び出すときに ID として使用します。Eventarc トリガーのサービス アカウントには、関数を呼び出す権限が必要です。デフォルトでは、Cloud Run は Compute Engine のデフォルトのサービス アカウントを使用します。

    8. 受信リクエストの送信先であるサービスの URL パスを指定することもできます。これは、トリガーのイベントの送信先である宛先サービスの相対パスです。例: /、/route、route、route/subroute.

  6. 必須フィールドに値を入力したら、[トリガーを保存] をクリックします。

gcloud

gcloud CLI を使用して関数を作成する場合は、まず関数をdeployしてからトリガーを作成する必要があります。関数のトリガーを作成する手順は次のとおりです。

  1. サンプルコードを含むディレクトリで次のコマンドを実行して、関数をデプロイします。

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    次のように置き換えます。

    • FUNCTION: デプロイする関数の名前。このパラメータは省略できますが、省略すると名前の入力を求められます。

    • FUNCTION_ENTRYPOINT: ソースコード内の関数のエントリ ポイント。これは、関数の実行時に Cloud Run が実行するコードです。このフラグには、ソースコード内に存在する関数名または完全修飾クラス名を指定する必要があります。

    • BASE_IMAGE_ID: 関数のベースイメージ環境。ベースイメージと各イメージに含まれるパッケージの詳細については、ランタイム ベースイメージをご覧ください。

    • REGION: 関数をデプロイする Google Cloud リージョン。例: us-central1

  2. 次のコマンドを実行して、イベントをフィルタするトリガーを作成します。

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.firestore.document.v1.created" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    次のように置き換えます。

    • TRIGGER_NAME: トリガーの名前。

    • EVENTARC_TRIGGER_LOCATION: Eventarc トリガーのロケーション。一般に、Eventarc トリガーのロケーションは、イベントをモニタリングする Google Cloud リソースのロケーションと一致する必要があります。ほとんどの場合、関数も同じリージョンにデプロイする必要があります。詳細については、Eventarc のロケーションをご覧ください。

    • FUNCTION: デプロイする関数の名前。

    • REGION: 関数の Cloud Run リージョン。

    • PROJECT_NUMBER は、Google Cloud プロジェクト番号に置き換えます。Eventarc トリガーはサービス アカウントにリンクされ、関数を呼び出すときに ID として使用します。Eventarc トリガーのサービス アカウントには、関数を呼び出す権限が必要です。デフォルトでは、Cloud Run はデフォルトのコンピューティング サービス アカウントを使用します。

    • event-filters フラグには、トリガーがモニタリングするイベント フィルタを指定します。event-filters フィルタにすべて一致するイベントが関数の呼び出しをトリガーします。各トリガーには、サポートされているイベントタイプを指定する必要があります。作成後にイベント フィルタのタイプを変更することはできません。イベント フィルタのタイプを変更するには、新しいトリガーを作成して古いトリガーを削除する必要があります。（省略可）さらにフィルタを追加するには、--event-filters フラグを繰り返し、サポートされているフィルタを ATTRIBUTE=VALUE の形式で指定します。

次のステップ

  • 指定したコレクション内のドキュメントに変更を加えたときにトリガーされる関数の例をご覧ください。