Overview
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.
Enable the API
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:
Storage Admin (
roles/storage.admin
) role on the bucket for which you want to
configure Pub/Sub notifications
Pub/Sub Admin (
roles/pubsub.admin
) role on the project in
which you want to receive Pub/Sub notifications
These predefined roles contain the permissions required to configure and view
Pub/Sub notifications. To see the exact permissions that are
required, expand the
Required permissions
section:
Required permissions
storage.buckets.get
storage.buckets.update
pubsub.topics.create
pubsub.topics.setIamPolicy
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
.
REST APIs
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
REST APIs
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
.
REST APIs
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.
To remove the notification configuration you created, run
terraform destroy
from the folder containing your
Terraform file.
REST APIs
XML API
You cannot manage Pub/Sub notifications with the XML API.
What's next