Cloud Storage triggers (2nd gen)
In Cloud Functions, a Cloud Storage trigger enables a function to be called
in response to changes in
Cloud Storage
. When you
specify a Cloud Storage trigger for a function, you choose an event
type and specify a Cloud Storage bucket. Your function will be called
whenever a change occurs on an object (file) within the specified bucket.
The following Cloud Storage event types are supported:
Event
|
Event type
|
Description
|
Object finalized
|
google.cloud.storage.object.v1.finalized
(through Eventarc)
|
Occurs when a new object is created, or an existing object is
overwritten and a new generation of that object is created.
|
Object deleted
|
google.cloud.storage.object.v1.deleted
(through Eventarc)
|
Occurs when an object is permanently deleted.
|
Object archived
|
google.cloud.storage.object.v1.archived
(through Eventarc)
|
Occurs when a live version of an object becomes a noncurrent version.
See
Object versioning
for more information.
|
Object metadata updated
|
google.cloud.storage.object.v1.metadataUpdated
(through Eventarc)
|
Occurs when the
metadata
of an
existing object changes.
|
A Cloud Storage trigger is implemented as a
CloudEvent function
,
in which the Cloud Storage event data is passed to your function in
the
CloudEvents format
, and the CloudEvent data
payload is of type
StorageObjectData
.
The
Google Events
repository contains additional resources for working with event data.
Permissions
In order to use Cloud Storage triggers in Cloud Functions,
the
Cloud Storage service agent
must have the
Pub/Sub Publisher
(
roles/pubsub.publisher
)
IAM role on your project.
Deployment
You can specify a Cloud Storage trigger when you deploy a function. See
Deploy a Cloud Function
for
general instructions on how to deploy a function, and see the following for
additional information specific to configuring Cloud Storage triggers
during deployment.
gcloud
If you are
deploying using the gcloud CLI
,
you can use the Cloud Storage
Object finalized
event type with the
following flags:
gcloud functions deploy
YOUR_FUNCTION_NAME
\
--trigger-bucket=
YOUR_STORAGE_BUCKET
\
[--retry] \
...
- The
--trigger-bucket
flag specifies the Cloud Storage bucket that the trigger will
monitor.
Object finalized
events within this bucket will trigger calls to your
function.
- The
--retry
flag controls
whether failed function calls are automatically retried. See
Retrying event-driven functions
for more information.
To use event types other than
Object finalized
, use the following flags:
gcloud functions deploy
YOUR_FUNCTION_NAME
--gen2
--trigger-event-filters="type=
EVENT_TYPE
"
--trigger-event-filters="bucket=
YOUR_STORAGE_BUCKET
"
...
When deploying functions, specify the bucket name alone without
the leading
gs://
; for example,
--trigger-event-filters="bucket=my-bucket"
.
Console
If you are
deploying using the Google Cloud console
,
you can configure a Cloud Storage trigger in the
Trigger
section:
- In the
Trigger type
field, choose
Cloud Storage
.
In the
Event type
field, choose a triggering event. The default is
google.cloud.storage.object.v1.finalized
.
For a Cloud Storage event that uses Cloud Audit Logs,
refer to the trigger configuration instructions
for an
Eventarc trigger
.
In the
Bucket
field, click
Browse
to select a
Cloud Storage bucket for the trigger to monitor. Changes to
objects within this bucket will trigger calls to your function.
Select or deselect the
Retry on failure
checkbox to control
whether Cloud Functions automatically retries a failed function
invocation. See
Retrying event-driven functions
for more information.
Click
More options
to perform additional configuration on your
trigger:
In the
Trigger type
field, specify one of
Google sources
,
Custom
, or
Third-party
:
Google sources
lets you specify triggers for
Pub/Sub, Cloud Storage,
Firestore, and other Google event providers.In
the
Eventarc trigger
pane, use the
Event provider
field to select the product that provides the type of event
you want to trigger your function. Then in the
Event
field,
select the event you want to use as a trigger.
The
Custom
option lets you produce and consume events from
your application code. Follow the prompts in the
Eventarc trigger
pane
to create a
channel
.
A channel is a resource that is used as a pipeline to deliver
custom events from producers to consumers. Custom events are
published to a channel and an Eventarc trigger
subscribes to those events.
The
Third-party
option let you integrate with non-Google
providers that offer an Eventarc source. See
third-party events in Eventarc
for details.
In the
Event
field, select a triggering event. The default is
google.cloud.storage.object.v1.finalized
.
Optionally, in the
Service account
field, select a service account to
be used as the identity of the Eventarc trigger. See
Trigger identity
for more information.
Click
Save trigger
.
Event delivery
Cloud Storage triggers are implemented with
Pub/Sub notifications for Cloud Storage
.
Events are subject to
Pub/Sub notification delivery guarantees
.
A Cloud Storage bucket can have up to 10 notification configurations
set to trigger for a specific event. Exceeding the bucket's notifications limits
will cause further function deployments to fail with an error like the following:
Cloud Storage bucket ...: Pub/Sub notification limit reached
See Cloud Storage
Quotas and limits
to learn more.
Next steps