Publishing object changes

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

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

Note: You cannot currently manage Pub/Sub Notifications with the Cloud Console, XML API, or Java client library.

Prerequisites

Before using this feature, you should:

1. Enable the 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 Pub/Sub Access Control for instructions on how to get these Pub/Sub permissions.

4. Note: The remaining steps are not necessary if you are using the gsutil tool.

   Have an existing 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 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.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string topic_name) {
  StatusOr<gcs::NotificationMetadata> notification =
      client.CreateNotification(bucket_name, topic_name,
                                gcs::payload_format::JsonApiV1(),
                                gcs::NotificationMetadata());

  if (!notification) {
    throw std::runtime_error(notification.status().message());
  }

  std::cout << "Successfully created notification " << notification->id()
            << " for bucket " << bucket_name << "\n";
  if (notification->object_name_prefix().empty()) {
    std::cout << "This notification will be sent for all objects in the"
              << " bucket\n";
  } else {
    std::cout << "This notification will be set sent only for objects"
              << " starting with the prefix "
              << notification->object_name_prefix() << "\n";
  }
  std::cout << "Full details for the notification:\n"
            << *notification << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

To create a notification configuration for a bucket using C#, see the CreateTopic reference documentation.

Go

For more information, see the Cloud Storage Go API reference documentation .

To create a notification configuration for a bucket using Go, see the BucketHandle reference documentation.

Java

For more information, see the Cloud Storage Java API reference documentation .

You cannot currently manage Pub/Sub Notifications with the Java client library.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

To create a notification configuration for a bucket using NodeJS, see the Bucket reference documentation.

PHP

For more information, see the Cloud Storage PHP API reference documentation .

To create a notification configuration for a bucket using PHP, see the Google\Cloud\Storage\Notification reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation .

To create a notification configuration for a bucket using Python, see the Buckets reference documentation.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

To create a notification configuration for a bucket using Ruby, see the Google::Cloud::Storage::Bucket reference documentation.

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://storage.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]

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string notification_id) {
  StatusOr<gcs::NotificationMetadata> notification =
      client.GetNotification(bucket_name, notification_id);

  if (!notification) {
    throw std::runtime_error(notification.status().message());
  }

  std::cout << "Notification " << notification->id() << " for bucket "
            << bucket_name << "\n";
  if (notification->object_name_prefix().empty()) {
    std::cout << "This notification is sent for all objects in the bucket\n";
  } else {
    std::cout << "This notification is sent only for objects starting with"
              << " the prefix " << notification->object_name_prefix() << "\n";
  }
  std::cout << "Full details for the notification:\n"
            << *notification << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

To list notification configurations associated with a bucket using C#, see the StorageClient reference documentation.

Go

For more information, see the Cloud Storage Go API reference documentation .

To list notification configurations associated with a bucket using Go, see the BucketHandle reference documentation.

Java

For more information, see the Cloud Storage Java API reference documentation .

You cannot currently manage Pub/Sub Notifications with the Java client library.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

To list notification configurations associated with a bucket using NodeJS, see the Bucket reference documentation.

PHP

For more information, see the Cloud Storage PHP API reference documentation .

To list notification configurations associated with a bucket using PHP, see the Google\Cloud\Storage\Bucket reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation .

To list notification configurations associated with a bucket using Python, see the Buckets reference documentation.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

To list notification configurations associated with a bucket using Ruby, see the Google::Cloud::Storage::Bucket reference documentation.

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://storage.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.

Code samples

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string bucket_name, std::string notification_id) {
  google::cloud::Status status =
      client.DeleteNotification(bucket_name, notification_id);

  if (!status.ok()) {
    throw std::runtime_error(status.message());
  }

  std::cout << "Successfully deleted notification " << notification_id
            << " on bucket " << bucket_name << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

To delete a notification configuration for a bucket using C#, see the StorageClient reference documentation.

Go

For more information, see the Cloud Storage Go API reference documentation .

To delete a notification configuration for a bucket using Go, see the BucketHandle reference documentation.

Java

For more information, see the Cloud Storage Java API reference documentation .

You cannot currently manage Pub/Sub Notifications with the Java client library.

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

To delete a notification configuration for a bucket using NodeJS, see the Notification reference documentation.

PHP

For more information, see the Cloud Storage PHP API reference documentation .

To delete a notification configuration for a bucket using PHP, see the Google\Cloud\Storage\Notification reference documentation.

Python

For more information, see the Cloud Storage Python API reference documentation .

To delete a notification configuration for a bucket using Python, see the Notification reference documentation.

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

To delete a notification configuration for a bucket using Ruby, see the Google::Cloud::Storage::Notification reference documentation.

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://storage.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 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 Pub/Sub Notifications for Cloud Storage.
• Learn how to Use Pub/Sub for Long-running Tasks.