Cloud Storage triggers

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
  • 2nd gen: google.cloud.storage.object.v1.finalized (through Eventarc)
  • 1st gen: 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
  • 2nd gen: google.cloud.storage.object.v1.deleted (through Eventarc)
  • 1st gen: google.storage.object.delete
Occurs when an object is permanently deleted.
Object archived
  • 2nd gen: google.cloud.storage.object.v1.archived (through Eventarc)
  • 1st gen: google.storage.object.archive
Occurs when a live version of an object becomes a noncurrent version. See Object versioning for more information.
Object metadata updated
  • 2nd gen: google.cloud.storage.object.v1.metadataUpdated (through Eventarc)
  • 1st gen: 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:

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

Permissions

In order to use Cloud Storage triggers in Cloud Functions (2nd gen), the Cloud Storage service agent must have the Pub/Sub Publisher (roles/pubsub.publisher) IAM role on your project. This requirement does not apply to Cloud Functions (1st gen).

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:

  • For Cloud Functions (2nd gen):

    gcloud functions deploy YOUR_FUNCTION_NAME \
    --gen2 \
    --trigger-event-filters="type=EVENT_TYPE" \
    --trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" \
    ...
    

    When deploying 2nd gen functions, specify the bucket name alone without the leading gs://; for example, --trigger-event-filters="bucket=my-bucket".

  • For Cloud Functions (1st gen):

    gcloud functions deploy YOUR_FUNCTION_NAME \
    --trigger-event=EVENT_TYPE \
    --trigger-resource=YOUR_STORAGE_BUCKET \
    ...
    

Legacy Cloud Storage events

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

gcloud functions deploy YOUR_FUNCTION_NAME \
--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.

  • For Cloud Functions (2nd gen):

    1. In the Trigger type field, choose Cloud Storage.
    2. 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.

    3. 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.

    4. 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.

    5. 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.

    6. Click Save trigger.

  • For Cloud Functions (1st gen):

    1. In the Trigger type field, select Cloud Storage.
    2. In the Event type field, select an event type.
    3. 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.
    4. 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

See Cloud Storage Quotas and limits to learn more.

Next steps