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.

Note: The Cloud Pub/Sub Notifications feature is a separate feature from Object Change Notifications. Cloud Pub/Sub Notifications sends notifications to Cloud Pub/Sub, while Object Change Notifications sends HTTPS notifications to a client application that you've set up.

Note: You cannot currently manage Cloud Pub/Sub Notifications with the GCP Console or XML API.

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:

   • If you own the project that contains the bucket, you most likely have the necessary permission.

   • If you use IAM, you should have storage.buckets.update permission. See Using IAM Permissions for instructions on how to do this.

   • If you use ACLs, you should have OWNER permission. See Setting ACLs for instructions on how to do this.

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. Note: The remaining steps are not necessary if you are using the gsutil tool.

   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.

   Note: There may be a delay of several seconds between assigning the role and having it applied to your service account. If you grant this permission programmatically, wait 30 seconds before configuring Cloud Storage.

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

• Learn more about Cloud Pub/Sub Notifications for Cloud Storage.
• Create a subscription in Pub/Sub to view notifications sent by Cloud Storage.
• See a Python example app of polling for notifications on GitHub.
• Create a photo album that uses Cloud Pub/Sub Notifications for Cloud Storage.
• Learn how to Use Cloud Pub/Sub for Long-running Tasks.