The Wayback Machine - https://web.archive.org/web/20190722002717/https://cloud.google.com/storage/docs/reporting-changes

Registering object changes

This page describes how to set up and use Cloud Pub/Sub Notifications for 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

Before using this feature, 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 pubsub.topics.setIamPolicy permission. If you create a topic, you typically have pubsub.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.

  6. Use the email address that you obtained in the previous step to give the service account the IAM role pubsub.publisher for the desired Cloud Pub/Sub topic.

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, gsutil creates one 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/[PROJECT_ID]/topics/[TOPIC_NAME]",
"payload_format": "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.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

This page
Documentation feedback
Cloud Storage
Product feedback
Need help? Visit our support page.