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.
Prerequisites
Before using this feature, you should:
Enable the Pub/Sub API for the project that will receive notifications.
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.
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 havepubsub.topics.setIamPolicy
for it.See Pub/Sub Access Control for instructions on how to get these Pub/Sub permissions.
-
Have an existing Pub/Sub topic that you wish to send notifications to.
Get the email address of the service account associated with the project that contains your Cloud Storage bucket.
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.
Applying a notification configuration
The following steps add a notification configuration to your bucket that sends notifications for all supported events.
gsutil
Use the gsutil notification create
command, replacing
PLACEHOLDERS
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.
To send notifications for a subset of events, include the -e
flag.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
You cannot currently manage Pub/Sub Notifications with the Java client library.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Google::Cloud::Storage::Bucket
class reference documentation.
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a .json file that contains the following information, replacing
PLACEHOLDERS
with the appropriate values:{ "topic": "projects/PROJECT_ID/topics/TOPIC_NAME", "payload_format": "JSON_API_V1" }
To send notifications for a subset of events, include the
event_types
field in the body of your JSON request.Use
cURL
to call the JSON API with aPOST notificationConfigs
request, replacingPLACEHOLDERS
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
PLACEHOLDERS
with the appropriate values:
gsutil notification list gs://BUCKET_NAME
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
You cannot currently manage Pub/Sub Notifications with the Java client library.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Google::Cloud::Storage::Bucket
class reference documentation.
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aGET notificationConfigs
request, replacingPLACEHOLDERS
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
PLACEHOLDERS
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
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
You cannot currently manage Pub/Sub Notifications with the Java client library.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
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.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Google::Cloud::Storage::Notification
class reference documentation.
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Use
cURL
to call the JSON API with aDELETE notificationConfigs
request, replacingPLACEHOLDERS
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.