An Eventarc trigger declares your interest in a certain event or set of events. You can configure event routing by specifying filters for the trigger, including the event source, and the target workflow.
Events are delivered in the CloudEvents format through an HTTP request. The Workflows service converts the event to a JSON object (following the CloudEvents specification) and passes the event into the workflow execution as a workflow runtime argument. Make sure that the event size does not exceed 512 KB. Events larger than the maximum Workflows arguments size won't trigger workflow executions.
Cloud Firestore supports Auth Context as an extension attribute to the CloudEvents format. When you create a trigger, you can apply this event type attribute to filter events with authentication information.
These instructions show you how to configure event routing so that an execution of your workflow is triggered in response to a direct Cloud Firestore event. For more details, see the list of supported direct events.
Prepare to create a trigger
Before creating an Eventarc trigger for a target workflow, complete the following tasks.
Console
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Enable the Eventarc, Eventarc Publishing, Workflows, and Workflow Executions APIs.
If applicable, enable the API related to the direct events. For example, for Cloud Firestore events, enable the Cloud Firestore API.
If you don't already have one, create a user-managed service account, then grant it the roles and permissions necessary so that Eventarc can manage events for a target workflow.
In the Google Cloud console, go to the Service Accounts page.
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.
In the Service account description field, enter a description. For example,
Service account for event trigger
.Click Create and continue.
To provide appropriate access, in the Select a role list, select the required Identity and Access Management (IAM) roles to grant to your service account. For more information, see Roles and permissions for Workflows targets.
For additional roles, click
Add another role and add each additional role.Click Continue.
To finish creating the account, click Done.
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.
Enable the Eventarc, Eventarc Publishing, Workflows, and Workflow Executions APIs:
gcloud services enable eventarc.googleapis.com \ eventarcpublishing.googleapis.com \ workflows.googleapis.com \ workflowexecutions.googleapis.com
If applicable, enable the API related to the direct events. For example, for Cloud Firestore events, enable
firestore.googleapis.com
.If you don't already have one, create a user-managed service account, then grant it the roles and permissions necessary so that Eventarc can manage events for a target workflow.
Create the service account:
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
Replace
SERVICE_ACCOUNT_NAME
with the name of the service account. It must be between 6 and 30 characters, and can contain lowercase alphanumeric characters and dashes. After you create a service account, you cannot change its name.Grant the required Identity and Access Management (IAM) roles or permissions. For more information, see Roles and permissions for Workflows targets.
Create a trigger
You can create an Eventarc trigger with a deployed workflow as
the event receiver by using the Google Cloud CLI (gcloud
or Terraform), or
through the Google Cloud console.
Console
- In the Google Cloud console, go to the Eventarc Triggers page.
- Click Create trigger.
- Type a Trigger name.
This is the ID of the trigger and it must start with a letter. It can contain up to 63 lowercase letters, numbers, or hyphens.
- For the Trigger type, select Google sources.
- In the Event provider list, select
Cloud Firestore.
Note that the event provider name used in the associated Google Cloud documentation might not have a prefix of Cloud or Google Cloud. For example, on the console, Memorystore for Redis is referred to as Google Cloud Memorystore for Redis.
- In the Event type list, from the Direct events, select an event type.
- In the Event data content type list, select the encoding
of the event payload.
For direct events from Cloud Firestore, this must be application/protobuf and the event data is a byte array. For more information about the protobuf messages for Cloud Firestore events, see Common events. Note that you can use a Workflows standard library function to encode bytes to Base64 text. For more information, see Returning bytes.
- In the Region list, select the same region as the
Google Cloud service that is generating events.
For more information, see Eventarc locations.
- If applicable to the event provider, click Add filter
and specify the following:
- In the Attribute 1 field, depending on the direct event you chose, select a resource ID that can act as an event filter.
- Select an operator:
- Equal
- Path pattern: applicable to
document
(Native mode) andentity
(Datastore mode) resources. Use wildcards to respond to changes that match a pattern. A wildcard*
matches a single segment and a multi-segment wildcard**
matches zero or more segments in the pattern. For example:/users/*
or/users/{userId}
Matches all documents in the /users
collection. Does not match documents in sub-collections like/users/marie/messages/33e2IxYBD9enzS50SJ68
/users/**
Matches all documents in the /users
collection and documents in subcollections like/users/marie/messages/33e2IxYBD9enzS50SJ68
For more information, see Understand path patterns.
- In the Attribute value 1 field, depending on the operator that you chose, type the exact value or apply a path pattern.
- If more attribute filters are applicable, click Add filter and specify the appropriate values.
- Select the Service account that will invoke your service
or workflow.
Or, you can create a new service account.
This specifies the Identity and Access Management (IAM) service account email associated with the trigger and to which you previously granted specific roles required by Eventarc.
- In the Event destination list, select Workflows.
- Select a workflow.
This is the name of the workflow to pass events to. Events for a workflow execution are transformed and passed to the workflow as runtime arguments.
For more information, see Create a trigger for Workflows.
- Click Create.
After a trigger is created, the event source filters cannot be modified. Instead, create a new trigger and delete the old one. For more information, see Manage triggers.
gcloud
You can create a trigger by running a gcloud eventarc triggers create
command along with required and optional flags.
The flags differ depending on whether you are running Firestore in Native mode or in Datastore mode. For more information, see Choosing between Native mode and Datastore mode.
Native mode
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 mode
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"
Replace the following:
TRIGGER
: the ID of the trigger or a fully qualified identifier.
LOCATION
: the location of the Eventarc trigger. Alternatively, you can set theeventarc/location
property; for examplegcloud config set eventarc/location us-central1
.Cloud Firestore triggers for Eventarc are only available in certain locations and the trigger must be in the same location as the Cloud Firestore database. For more information, see Eventarc locations and Cloud Firestore locations.
-
DESTINATION_WORKFLOW
: the ID of the deployed workflow that receives the events from the trigger. The workflow can be in any of the Workflows supported locations and does not need to be in the same location as the trigger. However, the workflow must be in the same project as the trigger. -
DESTINATION_WORKFLOW_LOCATION
(optional): the location in which the destination workflow is deployed. If not specified, it is assumed that the workflow is in the same location as the trigger. EVENT_FILTER_TYPE
: the identifier of the event. An event is generated when an API call for the method succeeds. For long-running operations, the event is only generated at the end of the operation, and only if the action is performed successfully. For a list of supported event types, see Google event types supported by Eventarc.google.cloud.firestore.document.v1.created
: event is sent when a document is written to for the first timegoogle.cloud.firestore.document.v1.created.withAuthContext
: event with authentication information attributes is sent when a document is written to for the first timegoogle.cloud.firestore.document.v1.updated
: event is sent when a document already exists and has any value changedgoogle.cloud.firestore.document.v1.updated.withAuthContext
: event with authentication information attributes is sent when a document already exists and has any value changedgoogle.cloud.firestore.document.v1.deleted
: event is sent when a document is deletedgoogle.cloud.firestore.document.v1.deleted.withAuthContext
: event with authentication information attributes is sent when a document is deletedgoogle.cloud.firestore.document.v1.written
: event is sent when a document is created, updated, or deletedgoogle.cloud.firestore.document.v1.written.withAuthContext
: event with authentication information attributes is sent when a document is created, updated, or deleted.google.cloud.datastore.entity.v1.created
: event is sent when an entity is written to for the first timegoogle.cloud.datastore.entity.v1.created.withAuthContext
: event with authentication information attributes is sent when an entity is written to for the first timegoogle.cloud.datastore.entity.v1.updated
: event is sent when an entity already exists and has any value changedgoogle.cloud.datastore.entity.v1.updated.withAuthContext
: event with authentication information attributes is sent when an entity already exists and has any value changedgoogle.cloud.datastore.entity.v1.deleted
: event is sent when an entity is deletedgoogle.cloud.datastore.entity.v1.deleted.withAuthContext
: event with authentication information attributes is sent when an entity is deletedgoogle.cloud.datastore.entity.v1.written
: event is sent when an entity is created, updated, or deletedgoogle.cloud.datastore.entity.v1.written.withAuthContext
: event with authentication information attributes is sent when an entity is created, updated, or deleted
Cloud Firestore supports the following event types in Native mode only.
Cloud Firestore supports the following event types in Datastore mode only. Data objects in Firestore in Datastore mode are known as entities.
DATABASE
: the Firestore database. For the default database name, use(default)
.NAMESPACE
(optional): the Firestore database namespace. For the default namespace in Datastore mode, use(default)
. If not specified, a wildcard match (*
) to any occurrences is made.DOCUMENT
(optional): applicable to database instances running in Native mode only. The database path from which you want to receive events from when data is created, updated, or deleted in that path. The operator can be one of the following:- Equal; for example,
--event-filters="document=DOCUMENT"
- Path pattern; for example,
--event-filters-path-pattern="document=DOCUMENT"
.Use wildcards to respond to changes in documents that match a pattern. A wildcard
*
matches a single segment and a multi-segment wildcard**
matches zero or more segments in the pattern. For example:/users/*
or/users/{userId}
Matches all documents in the /users
collection. Doesn't match documents in sub-collections like/users/marie/messages/33e2IxYBD9enzS50SJ68
/users/**
Matches all documents in the /users
collection and documents in subcollections like/users/marie/messages/33e2IxYBD9enzS50SJ68
- Equal; for example,
ENTITY
(optional): applicable to database instances running in Datastore mode only. The database path from which you want to receive events from when data is created, updated, or deleted in that path. The operator can be one of the following:- Equal; for example,
--event-filters="document=ENTITY"
- Path pattern; for example,
--event-filters-path-pattern="ENTITY=ENTITY"
For more information, see Understand path patterns.
Note that you might need to escape characters in kind IDs and entity IDs. Escaping a character lets the event filter correctly interpret the ID. For more information, see Character escaping.
- Equal; for example,
EVENT_DATA_CONTENT_TYPE
: the encoding of the event payload. For direct events from Firestore, this must beapplication/protobuf
and the event data is a byte array. For more information about the protobuf messages for Cloud Firestore events, see Common events. Note that you can use a Workflows standard library function to encode bytes to Base64 text. For more information, see Returning bytes.-
SERVICE_ACCOUNT_NAME
: the name of the IAM service account you created to which you granted specific roles required by Workflows. -
PROJECT_ID
: your Google Cloud project ID
Notes:
- For direct events from Cloud Firestore, the encoding
of the event payload is
application/protobuf
. - The
--event-filters="type=EVENT_FILTER_TYPE"
flag is required. If no other event filter is set, events for all resources are matched. EVENT_FILTER_TYPE
cannot be changed after creation. To changeEVENT_FILTER_TYPE
, create a new trigger and delete the old one.- Each trigger can have multiple event filters, comma delimited in one
--event-filters
=[ATTRIBUTE
=VALUE
,...] flag, or you can repeat the flag to add more filters. Only events that match all the filters are sent to the destination. Wildcards and regular expressions are not supported; however, when using the--event-filters-path-pattern
flag, you can define a resource path pattern. - The
--service-account
flag is used to specify the Identity and Access Management (IAM) service account email associated with the trigger.
Example:
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"
This command creates a trigger called helloworld-trigger
for
the event identified as google.cloud.firestore.document.v1.updated
in the
my-database
database instance running in Native mode, and
filters events for document
paths
that match users/my-document-
.
Terraform
You can create a trigger for a workflow using Terraform. For details, see Trigger a workflow using Eventarc and Terraform.
List a trigger
You can confirm the creation of a trigger by listing Eventarc triggers using the Google Cloud CLI or through the Google Cloud console.
Console
In the Google Cloud console, go to the Eventarc Triggers page.
This page lists your triggers in all locations, and includes details such as names, regions, event providers, destinations, and more.
To filter your triggers:
- Click Filter or the Filter triggers field.
- In the Properties list, select an option to filter the triggers by.
You can select a single property or use the logical operator OR
to add
more properties.
To sort your triggers, beside any supported column heading, click
Sort.gcloud
Run the following command to list your triggers:
gcloud eventarc triggers list --location=-
This command lists your triggers in all locations, and includes details such as names, types, destinations, and statuses.
What's next
- Learn more about using Eventarc and Cloud Firestore.
- Trigger a workflow using Eventarc and Terraform.
- Learn more about Eventarc.
- Learn how to manage triggers.