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:
- Learn about the publishing workflow.
- Create a topic.
- Choose and create a subscription.
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
The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, see the migration guide to v2. To see a list of v1 code samples, see the deprecated code samples.
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.