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)google.storage.object.delete
google.storage.object.archive
google.storage.object.metadataUpdate
For example, the gcloud
command shown below uses
the google.storage.object.finalize
trigger type to deploy a function that is
invoked whenever the specified Cloud Storage bucket is written to.
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.
For example, the following function logs relevant data when an event occurs:
Node.js
Python
Go
Java
C#
Ruby
Deploying the function
To deploy the function with an object finalize trigger, run the following command in the directory that contains the function code:
Node.js
gcloud functions deploy helloGCS \ --runtime nodejs10 \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:
nodejs10
nodejs12
nodejs14
(public preview)
Python
gcloud functions deploy hello_gcs \ --runtime python38 \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:
python37
python38
python39
(public preview)
Go
gcloud functions deploy HelloGCS \ --runtime go113 \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:
go111
(Deprecated)go113
Java
gcloud functions deploy java-gcs-function \ --entry-point HelloGcs \ --runtime java11 \ --memory 512MB \
--trigger-resource YOUR_TRIGGER_BUCKET_NAME \
--trigger-event google.storage.object.finalize
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 ruby26 \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:
ruby26
ruby27
where YOUR_TRIGGER_BUCKET_NAME
is the name of the Cloud
Storage Bucket that the function will monitor.
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
The events are delivered via
Pub/Sub notifications from Cloud Storage.
Setting up too many notifications registered against the same bucket may exhaust
the notification limit for the bucket and make it impossible to create the
function, as indicated by the error Cloud Storage bucket ...: Pub/Sub
notification limit reached
.
The bucket can have up to 10 notification configurations set to trigger for a specific event. See more quotas and limitations in the Cloud Storage Quotas & Limits page.
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 a background function that is triggered by Cloud Storage.