This document explains how to create, update, view, and delete a Pub/Sub topic. This document also explains how to name topics and subscriptions.
Properties of a topic
When you create or update a topic, you must specify its properties.
Add a default subscription. Adds a default subscription to the Pub/Sub topic. You can create another subscription for the topic after the topic is created. The default subscription has the following properties:
- Subscription ID of
-sub
- Pull delivery type
- Message retention duration of seven days
- Expiration after 31 days of inactivity
- Acknowledgment deadline of 10 seconds
- Immediate retry policy
- Subscription ID of
Schema. A schema is a format that the message data field must follow. A schema is a contract between the publisher and subscriber that Pub/Sub enforces. Topic schemas help standardize message types and permissions to allow them to be consumed by different teams in your organization. Pub/Sub creates a central authority for message types and permissions. To create a topic with schema, see Create and manage schemas.
Message retention duration. Specifies how long the Pub/Sub topic retains messages after publication. After the message retention duration is over, Pub/Sub might discard the message regardless of its acknowledgment state. Message storage fees are charged for storing all messages published to the topic.
- Default = Not enabled
- Minimum value = 10 minutes
- Maximum value = 31 days
Use a customer-managed encryption key (CMEK). Specifies if the topic is encrypted with a CMEK. Pub/Sub encrypts messages with Google-managed keys by default. If you specify this option, Pub/Sub uses the envelope encryption pattern with CMEK. In this approach, Cloud KMS does not encrypt the messages. Instead, Cloud KMS encrypts the Data Encryption Keys (DEKs) that Pub/Sub creates for each topic. Pub/Sub encrypts the messages using the newest DEK that was generated for the topic. Pub/Sub decrypts the messages shortly before they are delivered to subscribers. For more information about creating a key, see Configure message encryption.
Guidelines to name a topic or a subscription
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/ID
project-identifier.
Must be the project ID, available from the Google Cloud console. For example,projects/sampleproject/topics/sampletopic
.collection.
Must be one ofsubscriptions
,snapshots
, ortopics
.ID.
Must conform to the following guidelines:- 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+
, and percent signs%
You can use the special characters in the preceding list in resource names without URL-encoding. However, you must ensure that any other special characters are properly encoded or decoded when you use them in URLs. For example,
mi-tópico
is an invalid relative-name. However,mi-t%C3%B3pico
is valid. This format is important when you make REST calls.- Not begin with the string
Create a topic
Create a topic before you can publish or subscribe to it.
Console
To create a topic, follow these steps:
In the console, go to the Pub/Sub Topics page.
Click Create topic.
In the Topic ID field, enter an ID for your topic.
Retain the option Add a default subscription.
Do not select the other options.
Click Create topic.
gcloud
To create a topic, run the
gcloud pubsub topics create
command:
gcloud pubsub topics create TOPIC_ID
To create a topic, use the
The request must be authenticated with an access token in the
Where: Response:REST
projects.topics.create
method:Authorization
header. To obtain an access token for the current
Application Default Credentials: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
{
"name": "projects/PROJECT_ID/topics/TOPIC_ID"
}
Before trying this sample, follow the C++ setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C++ API reference documentation.
Before trying this sample, follow the C# setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C# API reference documentation.
Before trying this sample, follow the Go setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Go API reference documentation.
Before trying this sample, follow the Java setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Java API reference documentation.
Before trying this sample, follow the Node.js setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Node.js API reference documentation.
Before trying this sample, follow the PHP setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub PHP API reference documentation.
Before trying this sample, follow the Python setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Python API reference documentation.
Before trying this sample, follow the Ruby setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Organization policy constraints
Organizational policies can restrict topic creation, for example, a policy can restrict message storage in a Compute Engine region. To avoid topic creation errors, examine and update organizational policies, as needed, before creating a topic.
If your project is newly created, wait a few minutes for the organization policy to initialize before creating a topic.
Create a topic with a schema
While creating a topic, you might want to assign it a schema.
The following are some guidelines about using schemas:
- You cannot add schemas to existing topics.
- You can specify a schema only when you create a topic.
- After a schema is associated with a topic, you cannot update the schema or remove its association with that topic.
- You can apply the same schema to other new topics.
- If you delete a schema, publishing to all associated topics fails.
To know more about schemas, see Create and manage schemas.
Console
To create a topic and assign it a schema, follow these steps:
In the console, go to the Pub/Sub topics page.
Click Create topic.
In the Topic ID field, enter an ID for your topic.
Check the box for Use a schema. Leave the other options in their default settings.
Click Select a Pub/Sub schema and select Create a new schema. If you want to use an existing schema, skip to step 7.
In the Schema ID field, enter an ID for your schema.
For Schema type, select either Avro or Protocol Buffer.
In the Schema definition field, enter the Avro of Protocol Buffer definition for your schema.
Click Create to save the schema.
In the Create a topic dialog window, search for your schema in the Select a Pub/Sub schema field.
Click Create to save the topic and assign it with the selected schema.
gcloud
To create a topic assigned with a previously created schema, run the
gcloud pubsub topics create
command:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID
Where:
- TOPIC_ID is the ID for the topic that you're creating.
- ENCODING_TYPE is the encoding of messages validated against the
schema. This value must be set to either
JSON
orBINARY
. - SCHEMA_ID is the ID of an existing schema.
You can also assign a schema from a different Google Cloud project:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Where:
- SCHEMA_PROJECT is the project ID of the Google Cloud project for the schema.
- TOPIC_PROJECT is the project ID of the Google Cloud project for the topic.
REST
To create a topic, use the projects.topics.create
method:
Request:
The request must be authenticated with an access token in the
Authorization
header. To obtain an access token for the current
Application Default Credentials: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Request body:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" } }
Where:
- PROJECT_ID is your project ID.
- TOPIC_ID is your topic ID.
- SCHEMA_NAME is the name of the schema that messages published should be validated against. The format is:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE is the encoding of messages validated against the schema. This must be set to either
JSON
orBINARY
.
Response:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" } }
C++
Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation.
C#
Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.
Go
Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.
Java
Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub PHP API reference documentation.
Python
Before trying this sample, follow the Python setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Python API reference documentation.
Ruby
Before trying this sample, follow the Ruby setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Ruby API reference documentation.
Delete a topic
When you delete a topic, its subscriptions are not deleted. The
message backlog from the subscription 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.
In the console, go to the Pub/Sub Topics page. Select a topic and click Click Delete. The Delete topic window appears. Enter Console
delete
and then click Delete.
gcloud
To delete a topic, use the
gcloud pubsub topics delete
command:
gcloud pubsub topics delete TOPIC_ID
To delete a topic, use the
Request: The request must be authenticated with an access token in the
Where: Response: If the request is successful, the response is an empty JSON object.REST
projects.topics.delete
method:Authorization
header. To obtain an access token for the current
Application Default Credentials: gcloud auth application-default print-access-token
.
DELETE https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
Before trying this sample, follow the C++ setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C++ API reference documentation.
Before trying this sample, follow the C# setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C# API reference documentation.
Before trying this sample, follow the Go setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Go API reference documentation.
Before trying this sample, follow the Java setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Java API reference documentation.
Before trying this sample, follow the Node.js setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Node.js API reference documentation.
Before trying this sample, follow the PHP setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub PHP API reference documentation.
Before trying this sample, follow the Python setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Python API reference documentation.
Before trying this sample, follow the Ruby setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
List a topic
Console
In the console, go to the Pub/Sub Topics page.
The Topics page lists all the available topics.
To list topics, use the
gcloud
gcloud pubsub topics list
command:gcloud pubsub topics list
To list topics, use the
Request: The request must be authenticated with an access token in the
Where: Response:
Before trying this sample, follow the C++ setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C++ API reference documentation.
Before trying this sample, follow the C# setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub C# API reference documentation.
Before trying this sample, follow the Go setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Go API reference documentation.
Before trying this sample, follow the Java setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Java API reference documentation.
Before trying this sample, follow the Node.js setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Node.js API reference documentation.
Before trying this sample, follow the PHP setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub PHP API reference documentation.
Before trying this sample, follow the Python setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Python API reference documentation.
Before trying this sample, follow the Ruby setup instructions in the
Pub/Sub quickstart using client libraries.
For more information, see the
Pub/Sub Ruby API reference documentation.
REST
projects.topics.list
method:Authorization
header. To obtain an access token for the current
Application Default Credentials: gcloud auth application-default print-access-token
.
GET https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics
Authorization: Bearer ACCESS_TOKEN
{
"topics": [
{
"name": "projects/PROJECT_ID/topics/mytopic1",
...
},
{
"name": "projects/PROJECT_ID/topics/mytopic2",
...
}
]
}
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
By default, a maximum of 100 results are returned per query. You can specify an alternative value up to 1,000 using the page size parameter.
What's next
Choose the type of subscription for your topic.
Create a subscription for your topic.
Create or modify a topic with gcloud CLI.
Create or modify a topic with REST APIs.