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 に置き換えるワイルドカードは、必要な数だけ定義できます。マルチセグメント ワイルドカード（{username=**} など）は 1 つまで使用できます。

イベントの構造

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

{
    "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 を有効にする

必要なロール

デプロイ担当者アカウント、トリガー ID、Pub/Sub サービス エージェント（必要な場合）に次の IAM ロールを付与する必要があります（このロールの付与は自身で行うか、管理者に依頼します）。

デプロイ担当者のアカウントに必要なロール

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

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

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

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

トリガー ID に必要なロール

  1. 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 ロールを付与することを強くおすすめします。

  2. デフォルトでは、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.
  3. プロジェクトの 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

Pub/Sub サービス エージェントのオプションのロール

  • 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 リージョン。例: europe-west1

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

    各 event-filters フラグはイベントのタイプを指定します。関数は、イベントが event-filters フラグで指定されたすべての条件を満たした場合にのみトリガーされます。各トリガーには、Firestore への新しいドキュメントの書き込みや Cloud Storage へのファイルのアップロードなど、サポートされているイベントタイプを指定する event-filters フラグが必要です。作成後にイベント フィルタの種類を変更することはできません。イベント フィルタの種類を変更するには、新しいトリガーを作成して古いトリガーを削除する必要があります。（省略可）さらにフィルタを追加するには、--event-filters フラグを繰り返し、サポートされているフィルタを ATTRIBUTE=VALUE の形式で指定します。

Terraform

Cloud Run サービスの Eventarc トリガーを作成するには、Terraform を使用してトリガーを作成するをご覧ください。

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

使用するツールのタブをクリックして、手順を確認してください。

コンソール

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 リソースのロケーションと一致している必要があります。ほとんどの場合に、関数を同じリージョンにデプロイすることも必要です。Eventarc トリガーのロケーションの詳細については、Eventarc のロケーションについてをご覧ください。

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

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

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

gcloud

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

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

    gcloud 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リージョン。例: europe-west1

  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 フラグで指定されたすべての条件を満たした場合にのみトリガーされます。各トリガーには、Firestore への新しいドキュメントの書き込みや Cloud Storage へのファイルのアップロードなど、サポートされているイベントタイプを指定する event-filters フラグが必要です。作成後にイベント フィルタの種類を変更することはできません。イベント フィルタの種類を変更するには、新しいトリガーを作成して古いトリガーを削除する必要があります。（省略可）さらにフィルタを追加するには、--event-filters フラグを繰り返し、サポートされているフィルタを ATTRIBUTE=VALUE の形式で指定します。

Terraform

Cloud Run 関数の Eventarc トリガーを作成するには、Terraform を使用してトリガーを作成するをご覧ください。

詳細については、Cloud Run functions を使用してイベント トリガーで Firestore を拡張するをご覧ください。

次のステップ

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