Eventarc トリガーは、特定のイベントまたは一連のイベントに関心があることを宣言します。イベント ルーティングを構成するには、トリガーのフィルタ（イベントソースとターゲット ワークフローを含む）を指定します。
イベントは、HTTP リクエストを介して CloudEvents 形式で配信されます。Workflows サービスは、CloudEvents 仕様に従ってイベントを JSON オブジェクトに変換し、ワークフロー ランタイム引数としてワークフロー実行に渡します。イベントサイズが 512 KB を超えていないことを確認してください。Workflows の引数サイズの上限を超えるイベントはワークフローの実行をトリガーしません。
Cloud Firestore は、CloudEvents 形式の拡張属性として認証コンテキストをサポートしています。トリガーを作成するときに、このイベントタイプ属性を適用して、認証情報を含むイベントをフィルタリングできます。
以下では、Cloud Firestore 直接イベントに応答してワークフローの実行がトリガーされるように、イベント ルーティングを構成する方法について説明します。詳細については、サポートされている直接イベントのリストをご覧ください。
トリガーを作成する準備
ターゲット ワークフローの Eventarc トリガーを作成する前に、次の作業を完了します。
コンソール
Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。
Eventarc API、Eventarc Publishing API、Workflows API、Workflow Executions API を有効にします。
該当する場合は、ダイレクト イベントに関連する API を有効にします。たとえば、 Cloud Firestore イベントの場合はCloud Firestore API を有効にします。
アカウントがない場合は、ユーザー管理のサービス アカウントを作成し、Eventarc がターゲット ワークフローのイベントを管理できるように、必要なロールと権限を付与します。
Google Cloud コンソールで、[サービス アカウント] ページに移動します。
プロジェクトを選択します。
[サービス アカウント名] フィールドに名前を入力します。Google Cloud コンソールでは、この名前に基づいて [サービス アカウント ID] フィールドの値が設定されます。
[サービス アカウントの説明] フィールドに説明を入力します。例:
Service account for event trigger[作成して続行] をクリックします。
適切なアクセス権を付与するには、[ロールを選択] リストで、サービス アカウントに必要な Identity and Access Management（IAM）ロールを選択します。詳細については、Workflows ターゲットのロールと権限をご覧ください。
ロールを追加するには、[別のロールを追加] をクリックして各ロールを追加します。
[続行] をクリックします。
アカウントの作成を完了するには、[完了] をクリックします。
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.
Eventarc API、Eventarc Publishing API、Workflows API、Workflow Executions API を有効にします。
gcloud services enable eventarc.googleapis.com \ eventarcpublishing.googleapis.com \ workflows.googleapis.com \ workflowexecutions.googleapis.com
該当する場合は、直接イベントに関連する API を有効にします。たとえば、 Cloud Firestore イベントの場合は
firestore.googleapis.comを有効にします。アカウントがない場合は、ユーザー管理のサービス アカウントを作成し、Eventarc がターゲット ワークフローのイベントを管理できるように、必要なロールと権限を付与します。
サービス アカウントを作成します。
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
SERVICE_ACCOUNT_NAMEは、サービス アカウントの名前に置き換えます。6～30 文字で、小文字の英数字とダッシュを使用できます。作成したサービス アカウントの名前は変更できません。必要な Identity and Access Management（IAM）のロールまたは権限を付与します。詳細については、Workflows ターゲットのロールと権限をご覧ください。
トリガーを作成する
イベント レシーバとしてデプロイされたワークフローに Eventarc トリガーを作成するには、Google Cloud CLI（gcloud または Terraform）を使用するか、Google Cloud コンソールを使用します。
コンソール
- Google Cloud コンソールで、[Eventarc] の [トリガー] ページに移動します。
- [トリガーを作成] をクリックします。
- トリガー名を入力します。
これはトリガーの ID で、先頭は英字にする必要があります。63 文字以下とし、小文字、数字、ハイフンを使用できます。
- [トリガーのタイプ] で、[Google のソース] を選択します。
- [イベント プロバイダ] リストで「Cloud Firestore」を選択します。
関連する Google Cloud のドキュメントでは、イベント プロバイダ名の前に Cloud または Google Cloud が付いていない場合があります。たとえば、Memorystore for Redis はコンソールで Google Cloud Memorystore for Redis と表示されます。
- [イベントタイプ] リストで、直接イベントからイベントタイプを選択します。
- [イベントデータのコンテンツ タイプ] リストで、イベント ペイロードのエンコードを選択します。
Cloud Firestoreからの直接イベントの場合は、application/protobuf にする必要があります。イベントデータはバイト配列です。Cloud Firestore イベントの protobuf メッセージの詳細については、一般的なイベントをご覧ください。 Workflows 標準ライブラリ関数を使用して、バイトを Base64 テキストにエンコードできます。詳細については、返されるバイトをご覧ください。
- [リージョン] リストで、イベントを生成している Google Cloud サービスと同じリージョンを選択します。
詳細については、Eventarc のロケーションをご覧ください。
- イベント プロバイダで必要な場合は、[フィルタを追加] をクリックして、次の値を指定します。
- 選択した直接イベントに応じて、[属性 1] フィールドにイベント フィルタとして機能するリソース ID を選択します。
- 演算子を選択します。
- 等しい
- パスパターン:
document（ネイティブ モード）とentity（Datastore モード）のリソースに適用されます。パターンに一致する変更に応答するには、ワイルドカードを使用します。ワイルドカード*は単一のセグメントに一致し、マルチセグメント ワイルドカード**はパターン内の 0 個以上のセグメントに一致します。次に例を示します。/users/*または/users/{userId}/usersコレクション内のすべてのドキュメントに一致します。/users/marie/messages/33e2IxYBD9enzS50SJ68のようなサブコレクション内のドキュメントには一致しません。/users/**/usersコレクション内のすべてのドキュメントと、/users/marie/messages/33e2IxYBD9enzS50SJ68のようなサブコレクション内のドキュメントに一致します。詳細については、パスパターンについてをご覧ください。
- [属性の値 1] フィールドに、選択した演算子に応じて正確な値を入力するか、パスパターンを適用します。
- 適用可能な属性フィルタが他にもある場合は、[フィルタを追加] をクリックして適切な値を指定します。
- サービスまたはワークフローを呼び出すサービス アカウントを選択します。
新しいサービス アカウントを作成することもできます。
これにより、トリガーに関連付けられた Identity and Access Management（IAM）サービス アカウントのメールアドレスが設定されます。このメールアドレスには、Eventarc が必要とする特定のロールがすでに付与されています。
- [イベントの宛先] リストで、[Workflows] を選択します。
- ワークフローを選択します。
これは、イベントを渡すワークフローの名前です。ワークフロー実行用のイベントは、変換されてランタイム引数としてワークフローに渡されます。
詳細については、Workflows のトリガーを作成するをご覧ください。
- [作成] をクリックします。
トリガーの作成後は、イベントソースのフィルタを変更できません。代わりに、新しいトリガーを作成して古いトリガーを削除します。詳しくは、トリガーの管理をご覧ください。
gcloud
トリガーを作成するには、必須フラグとオプションのフラグを指定して gcloud eventarc triggers create コマンドを実行します。
フラグは、Firestore をネイティブ モードと Datastore モードのどちらで実行しているかによって異なります。詳細については、ネイティブ モードと Datastore モードの選択をご覧ください。
ネイティブ モード
gcloud eventarc triggers create TRIGGER \ --location=LOCATION \ --destination-workflow=DESTINATION_WORKFLOW \ --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \ --event-filters="type=EVENT_FILTER_TYPE" \ --event-filters="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="document=DOCUMENT" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
Datastore モード
gcloud eventarc triggers create TRIGGER \ --location=LOCATION \ --destination-workflow=DESTINATION_WORKFLOW \ --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \ --event-filters="type=EVENT_FILTER_TYPE" \ --event-filters="database=DATABASE" \ --event-filters="namespace=NAMESPACE" \ --event-filters-path-pattern="entity=ENTITY" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --service-account="MY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com"
次のように置き換えます。
TRIGGER: トリガーの ID または完全修飾識別子。
LOCATION: Eventarc トリガーのロケーション。eventarc/locationプロパティを設定することもできます（例:gcloud config set eventarc/location us-central1）。Eventarc 用 Cloud Firestore トリガーは特定のロケーションでのみ使用できます。トリガーは Cloud Firestore データベースと同じロケーションに存在する必要があります。詳細については、Eventarc のロケーションと Cloud Firestore のロケーションをご覧ください。
-
DESTINATION_WORKFLOW: トリガーからイベントを受け取る、デプロイ済みワークフローの ID。ワークフローは、Workflows でサポートされている任意のロケーションに配置できます。トリガーと同じロケーションに存在する必要はありません。ただし、ワークフローはトリガーと同じプロジェクトに存在する必要があります。 -
DESTINATION_WORKFLOW_LOCATION（省略可）: 宛先ワークフローがデプロイされるロケーション。指定しない場合、ワークフローはトリガーと同じロケーションにあるとみなされます。 EVENT_FILTER_TYPE: イベントの識別子。メソッドの API 呼び出しが成功すると、イベントが生成されます。長時間実行オペレーションの場合、イベントは、アクションが正常に完了したときにのみ、オペレーションの終了時に生成されます。サポートされているイベントタイプの一覧については、Eventarc でサポートされているイベントタイプをご覧ください。google.cloud.firestore.document.v1.created: ドキュメントが最初に書き込まれたときにイベントが送信されます。google.cloud.firestore.document.v1.created.withAuthContext: ドキュメントが初めて書き込まれたときに、認証情報属性を含むイベントが送信されます。google.cloud.firestore.document.v1.updated: ドキュメントがすでに存在し、値が変更されたときに、イベントが送信されます。google.cloud.firestore.document.v1.updated.withAuthContext: ドキュメントがすでに存在し、値が変更されたときに、認証情報の属性を含むイベントが送信されます。google.cloud.firestore.document.v1.deleted: ドキュメントが削除されたときにイベントが送信されます。google.cloud.firestore.document.v1.deleted.withAuthContext: ドキュメントが削除されたときに、認証情報属性を含むイベントが送信されます。google.cloud.firestore.document.v1.written: ドキュメントの作成、更新、または削除時にイベントが送信されます。google.cloud.firestore.document.v1.written.withAuthContext: ドキュメントが作成、更新、削除されたときに、認証情報属性を含むイベントが送信されます。google.cloud.datastore.entity.v1.created: エンティティが初めて書き込まれたときにイベントが送信されます。google.cloud.datastore.entity.v1.created.withAuthContext: エンティティが初めて書き込まれたときに、認証情報の属性を含むイベントが送信されます。google.cloud.datastore.entity.v1.updated: エンティティがすでに存在し、値が変更されたときにイベントが送信されます。google.cloud.datastore.entity.v1.updated.withAuthContext: エンティティがすでに存在し、値が変更されたときに、認証情報の属性を含むイベントが送信されます。google.cloud.datastore.entity.v1.deleted: エンティティが削除されたときにイベントが送信されます。google.cloud.datastore.entity.v1.deleted.withAuthContext: エンティティが削除されたときに、認証情報の属性を含むイベントが送信されます。google.cloud.datastore.entity.v1.written: エンティティが作成、更新、削除されたときにイベントが送信されます。google.cloud.datastore.entity.v1.written.withAuthContext: エンティティの作成、更新、削除時に、認証情報属性を含むイベントが送信されます。
Cloud Firestore は、ネイティブ モードのみで次のイベントタイプをサポートしています。
Cloud Firestore は、Datastore モードのみで次のイベントタイプをサポートしています。Datastore モードの Firestore では、データ オブジェクトをエンティティといいます。
DATABASE: Firestore データベース。 デフォルトのデータベース名には(default)を使用します。NAMESPACE（省略可）: Firestore データベースの名前空間。Datastore モードのデフォルトの名前空間には(default)を使用します。指定しない場合は、オカレンスとのワイルドカード照合（*）が行われます。DOCUMENT（省略可）: ネイティブ モードで実行されているデータベース インスタンスにのみ適用されます。そのパス内でデータが作成、更新、削除されたときにイベントを受信する、イベント受信元のデータベース パス。演算子には次のいずれかを指定できます。- 等しい。例:
--event-filters="document=DOCUMENT"。 - パスパターン。例:
--event-filters-path-pattern="document=DOCUMENT"。パターンに一致するドキュメントの変更に応答するには、ワイルドカードを使用します。ワイルドカード
*は単一のセグメントに一致し、マルチセグメント ワイルドカード**はパターン内の 0 個以上のセグメントに一致します。次に例を示します。
詳細については、パスパターンについてをご覧ください。/users/*または/users/{userId}/usersコレクション内のすべてのドキュメントに一致します。/users/marie/messages/33e2IxYBD9enzS50SJ68のようなサブコレクション内のドキュメントには一致しません。/users/**/usersコレクション内のすべてのドキュメントと、/users/marie/messages/33e2IxYBD9enzS50SJ68のようなサブコレクション内のドキュメントに一致します。
- 等しい。例:
ENTITY（省略可）: Datastore モードで実行されているデータベース インスタンスにのみ適用されます。そのパス内でデータが作成、更新、削除されたときにイベントを受信する、イベント受信元のデータベース パス。演算子には次のいずれかを指定できます。- 等しい。例:
--event-filters="document=ENTITY"。 - パスパターン。例:
--event-filters-path-pattern="ENTITY=ENTITY"。詳細については、パスパターンについてをご覧ください。
なお、種類 ID とエンティティ ID の文字をエスケープしなければならない場合があります。文字をエスケープすると、イベント フィルタで ID が正しく解釈されます。詳細については、文字のエスケープをご覧ください。
- 等しい。例:
EVENT_DATA_CONTENT_TYPE: イベント ペイロードのエンコード。Firestore からの直接イベントの場合は、application/protobufにする必要があります。イベントデータはバイト配列です。Cloud Firestore イベントの protobuf メッセージの詳細については、一般的なイベントをご覧ください。 Workflows 標準ライブラリ関数を使用して、バイトを Base64 テキストにエンコードできます。詳細については、返されるバイトをご覧ください。-
SERVICE_ACCOUNT_NAME: Workflows で必要な特定のロールを付与した IAM サービス アカウントの名前。 -
PROJECT_ID: 実際の Google Cloud プロジェクト ID
注:
- Cloud Firestoreからの直接イベントの場合、イベント ペイロードのエンコードは
application/protobufです。 --event-filters="type=EVENT_FILTER_TYPE"フラグは必須です。他のイベント フィルタが設定されていない場合は、すべてのリソースのイベントが照合されます。- 作成後に
EVENT_FILTER_TYPEを変更することはできません。EVENT_FILTER_TYPEを変更するには、新しいトリガーを作成して古いトリガーを削除します。 - 各トリガーには複数のイベント フィルタを指定できます。その場合は、
--event-filters=[ATTRIBUTE=VALUE,...] フラグにカンマ区切りで指定する必要があります。さらにフィルタを追加するには、このフラグを繰り返し指定します。すべてのフィルタに一致するイベントのみが宛先に送信されます。ワイルドカードと正規表現はサポートされていません。ただし、--event-filters-path-patternフラグを使用する場合は、リソースのパスパターンを定義できます。 --service-accountフラグには、トリガーに関連付けられた Identity and Access Management（IAM）サービス アカウントのメールアドレスを指定します。
例:
gcloud eventarc triggers create helloworld-trigger \
--location=us-east1 \
--destination-workflow=my-workflow \
--destination-workflow-location=us-east1 \
--event-filters="type=google.cloud.firestore.document.v1.updated" \
--event-filters="database=my-database" \
--event-filters-path-pattern="document=users/my-document-*" \
--event-data-content-type="application/protobuf" \
--service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"このコマンドは、ネイティブ モードで実行されている my-database データベース インスタンスに google.cloud.firestore.document.v1.updated として識別されるイベントのトリガーを helloworld-trigger という名前で作成し、users/my-document- と一致する document パスのイベントをフィルタします。
Terraform
Terraform を使用して、ワークフローのトリガーを作成できます。詳細については、Eventarc と Terraform を使用してワークフローをトリガーするをご覧ください。
トリガーを一覧表示する
トリガーの作成を確認するには、Google Cloud CLI または Google Cloud コンソールを使用して Eventarc トリガーを一覧表示します。
コンソール
Google Cloud コンソールで、[Eventarc] の [トリガー] ページに移動します。
このページには、すべてのロケーションのトリガーが一覧表示されます。また、名前、リージョン、イベント プロバイダ、宛先などの詳細情報も表示されます。
トリガーをフィルタするには:
- [ フィルタ] フィールドまたは [トリガーをフィルタリング] フィールドをクリックします。
- [プロパティ] リストで、トリガーをフィルタするオプションを選択します。
1 つのプロパティを選択することも、論理演算子
ORを使用して複数のプロパティを追加することもできます。トリガーを並べ替えるには、サポートされている列見出しの横にある [ 並べ替え] をクリックします。
gcloud
次のコマンドを実行してトリガーを一覧取得します。
gcloud eventarc triggers list --location=-
すべてのロケーションのトリガーが一覧表示されます。名前、タイプ、宛先、ステータスなどの詳細情報も表示されます。
次のステップ
- Eventarc と Cloud Firestore の使用方法を学習する。
- Eventarc と Terraform を使用してワークフローをトリガーする。
- Eventarc の詳細を学習する。
- トリガーを管理する方法を確認する。