Registering Object Changes

This page describes how to set up and use Google Cloud Pub/Sub Notifications for Google Cloud Storage. Cloud Pub/Sub Notifications allow you to track changes to your Cloud Storage objects. To learn more about Cloud Pub/Sub for Cloud Storage, see the Notifications concept page.

Prerequisites

gsutil

Before using this feature with the gsutil command-line tool, you should:

  1. Enable the Cloud Pub/Sub API for the project that will receive notifications. See Using IAM Permissions for instructions on how to do this.

    Enable the API

  2. Have sufficient permissions on the bucket you wish to monitor:

  3. Have sufficient permissions on the project that will receive notifications:

    • If you own the project that will receive notifications, you most likely have the necessary permission.

    • If you plan to create topics for receiving notifications, you should have pubsub.topics.create permission.

    • Whether you plan to use new or existing topics, you should have projects.topics.setIamPolicy permission. If you create a topic, you typically have projects.topics.setIamPolicy for it.

      See Cloud Pub/Sub Access Control for instructions on how to get these Cloud Pub/Sub permissions.

JSON

Before using this feature with the JSON API, you should:

  1. Enable the Cloud Pub/Sub API for the project that will receive notifications.

    Enable the API

  2. Have sufficient permissions on the bucket you wish to monitor:

  3. Have sufficient permissions on the project that will receive notifications:

    • If you own the project that will receive notifications, you most likely have the necessary permission.

    • If you plan to create topics for receiving notifications, you should have pubsub.topics.create permission.

    • Whether you plan to use new or existing topics, you should have projects.topics.setIamPolicy permission. If you create a topic, you typically have projects.topics.setIamPolicy for it.

      See Cloud Pub/Sub Access Control for instructions on how to get these Cloud Pub/Sub permissions.

  4. Have an existing Cloud Pub/Sub topic that you wish to send notifications to.

  5. Get the email address of the service account associated with the project that contains your Cloud Storage bucket.

    To find the email address of the service account, query the following URL, replacing [YOUR_PROJECT_NAME] with the name of the project that contains your bucket:

    https://www.googleapis.com/storage/v1/projects/[YOUR_PROJECT_NAME]/serviceAccount

    The result of this query should look similar to:

    {
     "email_address": "[YOUR_PROJECT_NAME]@gs-project-accounts.iam.gserviceaccount.com",
     "kind": "storage#serviceAccount"
    }

  6. Give the email address that you obtained in the previous step the IAM role pubsub.publisher for the desired Cloud Pub/Sub topic.

    See Cloud Pub/Sub Access Control for instructions on how to do this.

Applying a notification configuration

The following steps add a notification configuration to your bucket that sends notifications for all supported events. To send notifications for a subset of events, include the -e flag with your gsutil command or the event_types key in the body of your JSON request.

gsutil

Use the gsutil notification create command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil notification create -t [TOPIC_NAME] -f json gs://[BUCKET_NAME]

If you use a [TOPIC_NAME] that doesn't exist in your project, one is created for you.

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    {
       "topic": "projects/[YOUR_PROJECT_NAME]/topics/[YOUR_TOPIC_NAME]",
       "payloadFormat": "JSON_API_V1"
    }

  3. Use cURL to call the JSON API with a POST notificationConfigs request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X POST --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/notificationConfigs"

Listing notification configurations for a bucket

To list the notification configurations associated with a particular bucket:

gsutil

Use the gsutil notification list command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil notification list gs://[BUCKET_NAME]

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a GET notificationConfigs request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X GET \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/notificationConfigs"

Removing a notification configuration

To remove an existing notification configuration from your bucket:

gsutil

Use the gsutil notification delete command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil notification delete projects/_/buckets/[BUCKET_NAME]/notificationConfigs/[CONFIGURATION_NAME]

Once sent, it may take up to 30 seconds for all notifications triggered by the notification configuration to stop.

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.

  2. Use cURL to call the JSON API with a DELETE notificationConfigs request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X DELETE \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/notificationConfigs/[CONFIGURATION_NAME]"

Once sent, it may take up to 30 seconds for all notifications triggered by the notification configuration to stop.

Send feedback about...

Cloud Storage