This document provides information about publishing messages.
A publisher application creates and sends messages to a topic. Pub/Sub offers at-least-once message delivery and best-effort ordering to existing subscribers.
The general flow for a publisher application is:
- Create a message containing your data.
- Send a request to the Pub/Sub server to publish the message to the specified topic.
Before you begin
Before configuring the publish workflow, ensure you have completed the following tasks:
Required roles
To get the permissions that you need to publish messages to a topic,
ask your administrator to grant you the
Pub/Sub Publisher (roles/pubsub.publisher
) IAM role on the topic.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
You need additional permissions to create or update topics and subscriptions.
Message format
A message consists of fields with the message data and metadata. Specify at least one of the following in the message:
- The message data
- An ordering key
- Attributes with additional metadata
The Pub/Sub service adds the following fields to the message:
- A message ID unique to the topic
- A timestamp for when the Pub/Sub service receives the message
To learn more about messages, see Message format.
Publish messages
You can publish messages with the Google Cloud console, Google Cloud CLI, Pub/Sub API, and the client libraries. The client libraries can asynchronously publish messages.
The following samples demonstrate how to publish a message to a topic.
Console
To publish a message, follow these steps:
In the Google Cloud console, go to the Pub/Sub topics page.
Click the topic ID.
In the Topic details page under Messages, click Publish message.
In the Message body field, enter the message data.
Click Publish.
gcloud
To publish a message, use the gcloud pubsub topics publish command:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Replace the following:
- TOPIC_ID: the ID of the topic
- MESSAGE_DATA: a string with the message data
- KEY: the key of a message attribute
- VALUE: the value for the key of the message attribute
REST
To publish a message, send a POST request like the following:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Replace the following:
- PROJECT_ID: the project ID of the project with the topic
- TOPIC_ID: the ID of the topic
Specify the following fields in the request body:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Replace the following:
- KEY: the key of a message attribute
- VALUE: the value for the key of the message attribute
- MESSAGE_DATA: a base64-encoded string with the message data
The message must contain either a non-empty data field or at least one attribute.
If the request is successful, the response is a JSON object with the message ID. The following example is a response with a message ID:
{ "messageIds": [ "19916711285", ] }
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.
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.
After you publish a message, the Pub/Sub service returns the message ID to the publisher.
Use attributes to publish a message
You can embed custom attributes as metadata in Pub/Sub messages. Attributes are used to provide additional information about the message, such as its priority, origin, or destination. Attributes can also be used to filter messages on the subscription.
Follow these guidelines for using attributes in your messages:
Attributes can be text strings or byte strings.
You can have at most 100 attributes per message.
Attribute keys must not start with
goog
and must not exceed 256 bytes.Attribute values must not exceed 1024 bytes.
The message schema can be represented as follows:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
For publish-side duplicates, it's possible to see different publishTime
values
for the same client-side original message, even with the same messageId
.
The PubsubMessage
JSON schema is published as part of the
REST and
RPC
documentation. You can use custom attributes for event timestamps.
The following samples demonstrate how to publish a message with attributes to a topic.
Console
To publish a message with attributes, follow these steps:
In the Google Cloud console, go to the Topics page.
Click the topic for which you want to publish messages.
In the topic details page, click Messages.
Click Publish message.
In the Message body field, enter the message data.
Under Message attributes, click Add an attribute.
Enter a key-value pair.
Add more attributes, if required.
Click Publish.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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.
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.
Use ordering keys to publish a message
To receive messages in order in your subscriber clients, you must configure your publisher clients to publish messages with ordering keys.
To understand the concept of ordering keys, see Order messages.
Here is a list of key considerations for ordered messaging for publisher clients:
Ordering in a single publisher client: When a single publisher client publishes messages with the same ordering key in the same region, the subscriber client receives those messages in the exact order they were published. For example, if a publisher client publishes messages 1, 2, and 3 with the ordering key A, the subscriber client receives them in the order 1, 2, 3.
Ordering across multiple publisher clients: The order of messages received by subscriber clients is consistent with the order in which they were published in the same region, even when multiple publisher clients use the same ordering key. However, the publisher clients themselves don't have knowledge of this order.
For example, if publisher clients X and Y each publish messages with ordering key A, and X's message is received by Pub/Sub before Y's, then all subscriber clients receive X's message before Y's. If strict message order across different publisher clients is required, those clients must implement an additional coordination mechanism to ensure they don't publish messages with the same ordering key simultaneously. For example, a locking service can be used to maintain ownership of an ordering key while publishing.
Ordering across regions: The ordered delivery guarantee only applies when publishes for an ordering key are in the same region. If your publisher application publishes messages with the same ordering key to different regions, order cannot be enforced across those publishes. Subscribers can connect to any region and the ordering guarantee is still maintained.
When you run your application within Google Cloud, by default it connects to the Pub/Sub endpoint in the same region. Therefore, running your application in a single region within Google Cloud generally ensures you are interacting with a single region.
When you run your publisher application outside of Google Cloud or in multiple regions, you can guarantee you are connecting to a single region by using a locational endpoint when configuring your Pub/Sub client. All location endpoints for Pub/Sub point to single regions. To learn more about locational endpoints, see Pub/Sub endpoints. For a list of all locational endpoints for Pub/Sub, see List of locational endpoints.
Publishing failures: When publishing with an ordering key fails, queued-up messages of the same ordering key in the publisher fail, including future publish requests of this ordering key. You must resume publishing with ordering keys when such failures occur. For an example of resuming the publish operation, see Retry requests with ordering keys.
You can publish messages with ordering keys using the Google Cloud console, Google Cloud CLI, Pub/Sub API, or the client libraries.
Console
To publish a message with attributes, follow these steps:
In the Google Cloud console, go to the Topics page.
Click the topic for which you want to publish messages.
In the topic details page, click Messages.
Click Publish message.
In the Message body field, enter the message data.
In the Message ordering field, enter an ordering key.
Click Publish.
gcloud
To publish a message with an ordering key, use the
gcloud pubsub topics publish
command and the --ordering-key
flag:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Replace the following:
- TOPIC_ID: the ID of the topic
- MESSAGE_DATA: a string with the message data
- ORDERING_KEY: a string with an ordering key
REST
To publish a message with an ordering key, send a POST request like the following:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Replace the following:
- PROJECT_ID: the project ID of the project with the topic
- TOPIC_ID: the ID of the topic
Specify the following fields in the request body:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Replace the following:
- KEY: the key of a message attribute
- VALUE: the value for the key of the message attribute
- MESSAGE_DATA: a base64-encoded string with the message data
- ORDERING_KEY: a string with an ordering key
The message must contain either a non-empty data field or at least one attribute.
If the request is successful, the response is a JSON object with the message ID. The following example is a response with a message ID:
{ "messageIds": [ "19916711285", ] }
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.
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.
Monitor a publisher
Cloud Monitoring provides a number of metrics to monitor topics.
To monitor a topic and maintain a healthy publisher, see Maintain a healthy publisher.
What's next
To restrict the locations in which Pub/Sub stores message data, see Restricting Pub/Sub resource locations.
To publish messages with schema, see Schema overview.
To learn how to configure advanced delivery options, see the following: