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.
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. 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
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
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
[VALUES_IN_BRACKETS]
with the appropriate values:{ "topic": "projects/[PROJECT_ID]/topics/[TOPIC_NAME]", "payload_format": "JSON_API_V1" }
Use
cURL
to call the JSON API with aPOST 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
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
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, 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
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
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, 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.