This document provides information about how to create, delete, and administer Pub/Sub topics and subscriptions. For more information about publishing and accessing message data, see the Publisher Guide and Subscriber Overview.
Managing Topics
You can create, delete, and view topics using the API,
the Google Cloud Console, or the gcloud
command-line tool. See the
gcloud pubsub
reference
for a complete list of Pub/Sub API gcloud
commands.
For an introduction to the Cloud Console, see the Cloud Console Quickstart.
When you create a topic, you can also specify your own encryption keys. See Using customer-managed encryption keys.
Creating a topic
You must first create a topic before you can publish or subscribe to it. Here is an example showing how to create a topic:
Protocol
Request:
PUT https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic
Response:
200 OK
{ "name": "projects/myproject/topics/mytopic" }
Command-line
gcloud pubsub topics create myTopic
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Deleting a topic
Here is an example showing how to delete a topic:
Protocol
Request:
DELETE https://pubsub.googleapis.com/v1/projects/myproject/topics/mytopic
Response:
200 OK
{ "name": "projects/myproject/topics/mytopic" }
GCLOUD COMMAND
gcloud pubsub topics delete myTopic
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
When you delete a topic, its subscriptions are not deleted, and the
subscription's message backlog is available for subscribers. After a topic is
deleted, its subscriptions have the topic name _deleted-topic_
. If you try
to create a topic with the same name as a topic you had just deleted, expect
an error for a brief period of time after the deletion.
Listing topics
Here is an example showing how to get a list of topics:
Protocol
Request:
GET https://pubsub.googleapis.com/v1/projects/myproject/topics
Response:
200 OK
{ "topics": [ { "name": "projects/myproject/topics/mytopic1" }, { "name": "projects/myproject/topics/mytopic2" } ] }
GCLOUD COMMAND
gcloud pubsub topics list
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Managing Subscriptions
This section covers how to manage push and pull subscriptions. See the Subscriber Overview for an overview and comparison of pull and push subscriptions.
You must create a subscription to a topic before subscribers can receive messages published to the topic.
Also see the gcloud reference for subscriber commands.
Subscriptions have several properties that can be set at creation time or updated later, including:
Delivery method: By default, Pub/Sub subscriptions use the pull method. You can switch to push delivery by specifying a non-empty, valid HTTPS push endpoint URL.You can switch back to pull delivery by specifying an empty URL.
An acknowledgment deadline: If your code doesn't acknowledge the message before the deadline, the message is sent again. The default is 10 seconds. The maximum custom deadline you can specify is 600 seconds (10 minutes).
Creating subscriptions
You can use the following methods to create subscriptions:
The Cloud Console:
If you know the topic ID, you can use the subscriptions section of the console.
To create a subscription directly on the topic, go to the topics section of the console and open the topic.
The gcloud pubsub subscriptions create command.
The Client libraries:
Protocol
Request:
PUT https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription
{ "topic": "projects/someproject/topics/sometopic" // Only needed if you are using push delivery "pushConfig": { "pushEndpoint": "https://myproject.appspot.com/myhandler" } }
Response:
200 OK
{ "name": "projects/myproject/subscriptions/mysubscription", "topic": "projects/someproject/topics/sometopic", "pushConfig": { "pushEndpoint": "https://myproject.appspot.com/myhandler" }, "ackDeadlineSeconds": 10 }
GCLOUD COMMAND
gcloud pubsub subscriptions create mySubscription --topic myTopic
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
You can create push subscriptions by providing an HTTP endpoint URL, as shown in these examples:
GCLOUD COMMAND
gcloud pubsub subscriptions create mySubscription --topic myTopic --push-endpoint="https://myapp.appspot.com/push"
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Switching between push and pull subscriptions
You can use the Pub/Sub Cloud Console to change the subscription type. In the console, edit the subscription and change the Delivery Type to Pull or Push.
Alternately, you can use the gcloud command line tool command.. Specifically, use modify-push-config to modify the push endpoint URL.
- To convert a push subscription to pull, change the URL to an empty string.
- To convert a pull subscription to push, set a valid URL.
Examples: Modifying a subscription's endpoint or delivery mechanism
Once a subscription has been created, you can update the push endpoint of a subscription or switch from push to pull and vice versa. Here are examples showing how to update an existing pull or push subscription by specifying a non-empty, valid HTTPS push endpoint URL:
GCLOUD COMMAND
gcloud pubsub subscriptions modify-push-config mySubscription --push-endpoint="https://anotherapp.appspot.com/push"
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Modifying subscription expiration policies
By default, subscriptions expire after 31 days of inactivity. If Pub/Sub detects subscriber activity (such as open connections, active pulls, or successful pushes), the subscription deletion clock restarts.
To change this behavior, modify the subscription's expiration policy. You can set the policy duration when you create the subscription or modify it later. The minimum allowed value for an expiration policy is 1 day. There is no maximum. Use any of the following options to configure the policy:
The duration and expiration flags available in the gcloud subscription commands. For example:
alias pubsub='gcloud pubsub' # subscription that expires after one day of inactivity pubsub subscriptions create mySubscription --expiration-period=1d --topic myTopic # make the subscription non-expiring pubsub subscriptions update mySubscription --expiration-period=never
Support for expiration policies is available in the Pub/Sub Client Libraries.
RPC methods:
REST method:
Retaining unacknowledged and acknowledged messages
By default, Pub/Sub ensures that subscriptions retain
unacknowledged messages for 7 days from the moment of publication. You can set
a subscription's messageRetentionDuration
property to specify how
long after publication messages should be retained, up to a maximum of 7
days. After the duration specified in this property, Pub/Sub is
free to discard the message, regardless of its acknowledgment state. You can
also configure the subscription to retain acknowledged
messages for this duration. See Replaying and Discarding Messages.
Listing subscriptions
You can list all subscriptions in a project, or only subscriptions to a particular topic. See Access Control for details on limiting access, if needed. Here are examples showing how to list all subscriptions in a project.
GCLOUD COMMAND
gcloud pubsub subscriptions list
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Accessing subscriptions
Here are examples showing how to access subscriptions for a specific topic.
GCLOUD COMMAND
gcloud pubsub topics list-subscriptions myTopic
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Deleting subscriptions
Here are examples showing how to delete subscriptions in a project once they are no longer required.
GCLOUD COMMAND
gcloud pubsub subscriptions delete mySubscription
C#
Before trying this sample, follow the C# setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub C# API reference documentation .
Go
Before trying this sample, follow the Go setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Go API reference documentation .
Java
Before trying this sample, follow the Java setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Java API reference documentation .
Node.js
Before trying this sample, follow the Node.js setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Node.js API reference documentation .
PHP
Before trying this sample, follow the PHP setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub PHP API reference documentation .
Python
Before trying this sample, follow the Python setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Python API reference documentation .
Ruby
Before trying this sample, follow the Ruby setup instructions in the Cloud Pub/Sub Quickstart Using Client Libraries . For more information, see the Cloud Pub/Sub Ruby API reference documentation .
Resource names
A Pub/Sub resource name uniquely identifies a Pub/Sub resource, such as a subscription or topic, and must fit the following format:
projects/project-identifier/collection/relative-name
The project-identifier must be the project ID, available from the
Google Cloud Console. For example, projects/myproject/topics/mytopic
.
The collection must be one of subscriptions
or topics
.
The relative-name must:
- Not begin with the string
goog
. - Start with a letter
- Contain between 3 and 255 characters
Contain only the following characters:
- Letters:
[A-Za-z]
- Numbers:
[0-9]
- Dashes:
-
- Underscores:
_
- Periods:
.
- Tildes:
~
- Plus signs:
+
Percent signs:
%
The special characters in the above list can be used in resource names without URL-encoding. However, you must ensure that any other special characters are properly encoded/decoded when used in URLs. For example,
mi-tópico
is an invalid relative-name. However,mi-t%C3%B3pico
is valid.This is particularly important for REST calls.
- Letters: