This page describes how to configure your bucket to send notifications about object changes to a Pub/Sub topic. For information on subscribing to a Pub/Sub topic that receives notifications, see Choose a subscription type.
Before you begin
Before using this feature, complete the following instructions.
Enable the Pub/Sub API
Enable the Pub/Sub API for the project that will receive notifications.
Get required roles
To get the permissions that you need to configure and view Pub/Sub notifications for a bucket, ask your administrator to grant you the following roles. These predefined roles contain the permissions required to configure and view Pub/Sub notifications.
Storage Admin (
roles/storage.admin
) role on the bucket for which you want to configure Pub/Sub notificationsPub/Sub Admin (
roles/pubsub.admin
) role on the project in which you want to receive Pub/Sub notifications
You might be able to get these permissions with other predefined roles or custom roles.
See Use IAM with buckets for instructions on granting roles on buckets. See Controlling access for instructions on granting roles on projects and setting access controls for topics and subscriptions.
Make sure you have an existing Pub/Sub topic
If you haven't already, create a Pub/Sub topic to which you want to send notifications. This step is not necessary if you plan on using the Google Cloud CLI or Terraform to perform the instructions on this page.
Grant required role to your project's service agent
The following steps are not necessary if you plan on using the Google Cloud CLI or Terraform to perform the instructions on this page.
Get the email address of the service agent associated with the project that contains your Cloud Storage bucket.
Grant the service agent the Pub/Sub Publisher (
roles/pubsub.publisher
) role for the relevant Pub/Sub topic. See Controlling access for instructions on granting roles for topics.
Apply a notification configuration
The following steps add a notification configuration to your bucket that sends notifications for all supported events.
Console
You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.
Command line
Use the gcloud storage buckets notifications create
command:
gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.TOPIC_NAME
is the Pub/Sub topic to send notifications to. If you specify a topic that doesn't exist in your project, the command creates one for you.
To send notifications for a subset of events, include the
--event-types
flag.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Terraform
You can use a Terraform resource to add a notification configuration to a bucket.
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Create a JSON file that contains the following information:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_NAME", "payload_format": "JSON_API_V1" }
Where:
PROJECT_ID
is the ID for the project associated with the Pub/Sub topic that you want to send notifications to. For example,my-pet-project
.TOPIC_NAME
is the Pub/Sub topic to send notifications to. For example,my-topic
.
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:curl -X POST --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"
Where:
JSON_FILE_NAME
is the path for the file that you created in Step 2.BUCKET_NAME
is the name of the bucket you want notifications to be generated for. For example,my-bucket
.
XML API
You cannot manage Pub/Sub notifications with the XML API.
Get a notification configuration
To get a specific notification configuration that's associated with your bucket, complete the following steps:
Console
You cannot manage Pub/Sub notifications with the Google Cloud console. Use the Google Cloud CLI or one of the available client libraries instead.
Command line
Use the gcloud storage buckets notifications describe
command:
gcloud storage buckets notifications describe projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID
Where:
BUCKET_NAME
is the name of the bucket whose notification configuration you want to retrieve For example,my-bucket
.NOTIFICATION_ID
is the ID number of the relevant configuration. For example,5
.
If successful, the response looks similar to the following example:
etag: '132' id: '132' kind: storage#notification payload_format: JSON_API_V1 selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/notificationConfigs/132 topic: //pubsub.googleapis.com/projects/my-project/topics/my-bucket
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aGET notificationConfigs
request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"
Where:
BUCKET_NAME
is the name of the bucket whose notification configuration you want to retrieve. For example,my-bucket
.NOTIFICATION_ID
is the ID number of the notification configuration you want to retrieve. For example,5
.
XML API
You cannot manage Pub/Sub Notifications with the XML API.
List notification configurations for a bucket
To list all the notification configurations associated with a particular bucket:
Console
You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.
Command line
Use the gcloud storage buckets notifications list
command:
gcloud storage buckets notifications list gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket
whose notification configurations you want to list. For example,
my-bucket
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aGET notificationConfigs
request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"
Where
BUCKET_NAME
is the name of the bucket whose notification configurations you want to list. For example,my-bucket
.
XML API
You cannot manage Pub/Sub notifications with the XML API.
Remove a notification configuration
To remove an existing notification configuration from your bucket:
Console
You cannot manage Pub/Sub notifications with the Google Cloud console. Use the gcloud CLI or one of the available client libraries instead.
Command line
Use the gcloud storage buckets notifications delete
command:
gcloud storage buckets notifications delete projects/_/buckets/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID
Where:
BUCKET_NAME
is the name of the bucket whose notification configuration you want to delete. For example,my-bucket
.NOTIFICATION_ID
is the ID number of the configuration you want to delete. For example,5
.
If successful, the response looks similar to the following example:
Completed 1
Once sent, it might take up to 30 seconds for all notifications triggered by the notification configuration to stop.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Terraform
To remove the notification configuration you created, run
terraform destroy
from the folder containing your
Terraform file.
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aDELETE notificationConfigs
request:curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/NOTIFICATION_ID"
Where:
BUCKET_NAME
is the name of the bucket whose notification configuration you want to delete. For example,my-bucket
.NOTIFICATION_ID
is the ID number of the notification configuration you want to delete. For example,5
.
Once sent, it may take up to 30 seconds for all notifications triggered by the notification configuration to stop.
XML API
You cannot manage Pub/Sub notifications with the XML API.
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 that polls for notifications on GitHub.
Use Cloud Run functions to deliver events with a Cloud Storage trigger.