Google Cloud Storage Triggers
Cloud Functions uses event-driven functions to handle events from your Cloud infrastructure. For example, Cloud Functions can respond to change notifications emerging from Google Cloud Storage. These notifications can be configured to trigger in response to various events inside a bucket—object creation, deletion, archiving and metadata updates.
Event types
Cloud Storage events used by Cloud Functions are based on Cloud Pub/Sub Notifications for Google Cloud Storage and are provided in the Cloud Storage JSON API format.
Storage-triggered functions support four trigger types. These trigger type values are used upon function deployment to specify which Cloud Storage events will trigger your functions:
google.storage.object.finalize
(default)
Sample function code
The following sample function logs relevant data when an event occurs.
You specify the trigger type when you deploy the function. For example,
the deployment example below uses the function to log every time
an object is created by specifying the google.storage.object.finalize
trigger type.
For a full tutorial on running this code, see the Cloud storage tutorial:
Node.js
Python
Go
Java
C#
Ruby
PHP
Specifying the trigger type at deployment
The following gcloud
command deploys the function with an object.finalize
trigger.
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs16 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Node.js version:
nodejs16
(recommended)nodejs14
nodejs12
nodejs10
Python
gcloud functions deploy hello_gcs \ --runtime python39 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Python version:
python310
(preview)python39
(recommended)python38
python37
Go
gcloud functions deploy HelloGCS \ --runtime go116 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Go version:
go116
(recommended)go113
go111
Java
gcloud functions deploy java-gcs-function \ --entry-point functions.HelloGcs \ --runtime java11 \ --memory 512MB \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Java version:
java17
(preview)java11
(recommended)
C#
gcloud functions deploy csharp-gcs-function \ --entry-point HelloGcs.Function \ --runtime dotnet3 \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
Ruby
gcloud functions deploy hello_gcs --runtime ruby30 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred Ruby version:
ruby30
(recommended)ruby27
ruby26
PHP
gcloud functions deploy helloGCS --runtime php74 \You can use the following values for the
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
--runtime
flag to specify your preferred PHP version:
php81
(preview)php74
(recommended)
where YOUR_TRIGGER_BUCKET_NAME
is the name of the Cloud
Storage bucket that the function will monitor.
Object Finalize
Trigger type value: google.storage.object.finalize
This event is sent when a new object is created (or an existing object is overwritten, and a new generation of that object is created) in the bucket.
Object Delete
Trigger type value: google.storage.object.delete
This event is sent when an object is permanently deleted. Depending on the object versioning setting for a bucket this means:
For versioning buckets, this is only sent when a version is permanently deleted (but not when an object is archived).
For non-versioning buckets, this is sent when an object is deleted or overwritten.
Object Archive
Trigger type value: google.storage.object.archive
This event is sent when a live version of an object is archived or deleted.
This event is only sent for versioning buckets.
Object Metadata Update
Trigger type value: google.storage.object.metadataUpdate
This event is sent when the metadata of an existing object changes.
Event structure
Storage event data is delivered in the Cloud Storage object
format.
Event delivery mechanism
Events are delivered using Pub/Sub notifications from Cloud Storage. Events are subject to Pub/Sub's delivery guarantees.
Notifications limit
A bucket can have up to 10 notification configurations set to trigger for a specific event. Setting up too many notifications for the same bucket might exceed the notifications limit for the bucket and make it impossible to create the function, as indicated by the following error:
Cloud Storage bucket ...: Pub/Sub notification limit reached
If you reach the limit, you can't create a function until you take remedial action, such as removing notifications.
Learn more about the quotas and request limits for Cloud Storage.
Permissions
You must have sufficient permissions on the project that will receive notifications. This includes ensuring that you do the following:
Get the email address of the service agent associated with the project that contains your Cloud Storage bucket.
Use the email address that you obtained in the previous step to give the service agent the IAM role
pubsub.publisher
for the relevant Pub/Sub topic.
Learn more about configuring Pub/Sub notifications for Cloud Storage.
Legacy Cloud Storage triggers
The gcloud
command below deploys a function that is triggered by legacy
object change notifications on a
specific bucket. Generally, Cloud Pub/Sub notifications are
easier to use, more flexible, and more powerful than object change notifications.
However, these legacy notifications are supported for legacy functions already
consuming these events.
gcloud functions deploy YOUR_FUNCTION_NAME \ --trigger-resource YOUR_TRIGGER_BUCKET_NAME \ --trigger-event providers/cloud.storage/eventTypes/object.change \ FLAGS...
Argument | Description |
---|---|
--trigger-resource NAME |
The name of the Cloud Storage bucket the function watches for changes. |
--trigger-event NAME |
The name of the event type that the function wishes to receive. In this
case, it is the legacy object.change event. |
FLAGS... |
Additional flags you must specify during deployment, such as
--runtime . For a full reference, see the
gcloud functions deploy
documentation.
|
Next steps
See the Cloud Storage Tutorial for an example of how to implement an event-driven function that is triggered by Cloud Storage.