notification - Configure object change notification

notification - Configure object change notification


gsutil notification create -f (json|none) [-p prefix] [-t topic] [-m key:value]... [-t eventType]... bucket_url gsutil notification delete (notificationConfigName|bucket_url)... gsutil notification list bucket_url...


These notification sub-commands deal with configuring GCS's integration with Google Cloud Pub/Sub.


The create sub-command creates a notification config on a bucket, establishing a flow of event notifications from GCS to a Cloud Pub/Sub topic. As part of creating this flow, the create command also verifies that the destination Cloud Pub/Sub topic exists, creating it if necessary, and verifies that the GCS bucket has permission to publish events to that topic, granting the permission if necessary.

If a destination Cloud Pub/Sub topic is not specified with the -t flag, GCS will by default choose a topic name in the default project whose ID is the same the bucket name. For example, if the default project ID specified is 'default-project' and the bucket being configured is gs://example-bucket, the create command will use the Cloud Pub/Sub topic "projects/default-project/topics/example-bucket".

In order to enable notifications, a special GCS service account unique to each project must have the IAM permission "projects.topics.publish". This command will check to see if that permission exists and, if not, will attempt to grant it.


The create sub-command has the following options:

-e Specify an event type filter for this notification config. GCS will only send notifications of this type. You may specify this parameter multiple times to allow multiple event types. If not specified, GCS will send notifications for all event types. The valid types are:

OBJECT_FINALIZE - An object has been created.

OBJECT_METADATA_UPDATE - The metadata of an object has changed.

OBJECT_DELETE - An object has been permanently deleted.

OBJECT_ARCHIVE - A live GCS object has been archived.

-f Specifies the payload format of notification messages. Must be either "json" for a payload matches the object metadata for the JSON API, or "none" to specify no payload at all. In either case, notification details are available in the message attributes.
-m Specifies a key:value attribute that will be appended to the set of attributes sent to Cloud Pub/Sub for all events associated with this notification config. You may specify this parameter multiple times to set multiple attributes.
-o Specifies a prefix path filter for this notification config. GCS will only send notifications for objects in this bucket whose names begin with the specified prefix.
-c Skips creation and permission assignment of the Cloud Pub/Sub topic. This is useful if the caller does not have permission to access the topic in question, or if the topic already exists and has the appropriate publish permission assigned.
-t The Cloud Pub/Sub topic to which notifications should be sent. If not specified, this command will choose a topic whose project is controlled by -p and whose ID is the same as the GCS bucket name.


The list sub-command provides a list of notification configs belonging to a given bucket. The listed name of each notification config can be used with the delete sub-command to delete that specific notification config.

No object change notifications will be listed. Only Cloud Pub/Sub notification subscription configs will be listed.


The delete sub-command deletes notification configs from a bucket. If a notification config name is passed as a parameter, that notification config alone will be deleted. If a bucket name is passed, all notification configs associated with that bucket will be deleted.

Cloud Pub/Sub topics associated with this notification config will not be deleted by this command. Those must be deleted separately, for example with the gcloud command `gcloud beta pubsub topics delete`.

Object Change Notification subscriptions cannot be deleted with this command. For that, see the command `gsutil notification stopchannel`.

Notifications And Parallel Composite Uploads

By default, gsutil enables parallel composite uploads for large files (see gsutil help cp), which means that an upload of a large object can result in multiple temporary component objects being uploaded before the actual intended object is created. Any subscriber to notifications for this bucket will then see a notification for each of these components being created and deleted. If this is a concern for you, note that parallel composite uploads can be disabled by setting "parallel_composite_upload_threshold = 0" in your boto config file.

Send feedback about...

Cloud Storage Documentation