If you are creating a new function, see the Console Quickstart on Cloud Run. The content on this page only applies to existing legacy functions created with the Cloud Functions v1 API.

Cloud Storage triggers (1st gen)

In Cloud Run 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.storage.object.finalize`	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.storage.object.delete`	Occurs when an object is soft deleted. For more information, see Soft delete.
Object archived	`google.storage.object.archive`	Occurs when a live version of an object becomes a noncurrent version. For more information, see Object Versioning.
Object metadata updated	`google.storage.object.metadataUpdate`	Occurs when the metadata of an existing object changes.

For a function to use a Cloud Storage trigger, it must be implemented as an event-driven function:

If you use a CloudEvent function, the Cloud Storage event data is passed to your function in the CloudEvents format and the CloudEvent data payload is of type StorageObjectData.
If you use a background function, the Cloud Storage event data payload is passed directly to your function in the StorageObjectData format.

The Google Events repository contains additional resources for working with event data.

Deployment

You can specify a Cloud Storage trigger when you deploy a function. See Deploy a Cloud Run 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 \
--no-gen2 \
--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 

  --no-gen2 

  --trigger-event=EVENT_TYPE 

  --trigger-resource=YOUR_STORAGE_BUCKET 

  ...

Legacy Cloud Storage events

Legacy functions in Cloud Run functions (1st gen) use legacy object change notifications for Cloud Storage triggers:

gcloud functions deploy YOUR_FUNCTION_NAME \
--no-gen2 \
--trigger-event=providers/cloud.storage/eventTypes/object.change \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

This event type is supported for legacy functions already consuming these events. However, we don't recommend using this event type as it might be removed at a future date.

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, select Cloud Storage.
In the Event type field, select an event type.
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 failed function calls are automatically retried. See Retrying event-driven functions for more information.

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

You can work around this limitation by managing your own Pub/Sub topic and registering it for Cloud Storage notifications of the type you want your function to respond to. For example, you could configure a single notification for your chosen event (such as object creation) to a Pub/Sub topic. Then, have as many function subscribers as needed to the topic process the event and fan it out to multiple destinations. For example:

Create your own Pub/Sub topic.
Create a single notification configuration on your Cloud Storage bucket that triggers on a specific event (such as OBJECT_FINALIZE for object creation) and sends the event to your single Pub/Sub topic.
Create a function (or functions) triggered by your Pub/Sub topic.

See Cloud Storage Quotas and limits to learn more about Cloud Storage limitations.

Next steps

Learn how to write event-driven functions.
Learn how to deploy a Cloud Run function.
See the Cloud Storage function tutorial for an example of writing, deploying, and calling a function with a Cloud Storage trigger.