This document provides information about publishing messages.
To learn about creating, deleting, and administering topics and subscriptions, see Managing Topics and Subscriptions.
To restrict the locations in which message data is stored on a per-topic basis, see Restricting Pub/Sub resource locations.
To learn more about receiving messages, see the Subscriber Guide.
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, as explained in the Subscriber Overview.
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 desired topic.
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
If you're using the REST API, the message data must be base64-encoded.
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
Publishing messages
You can publish messages with the gcloud
command-line tool or the Pub/Sub API. The
client libraries can asynchronously publish messages.
Console
To publish a message, follow these steps:
In the Cloud Console, go to the Pub/Sub topics page.
Click the topic ID.
In the Topic details page, click Publish messages.
In the Message body field, enter the message data.
Optional: Add message attributes.
Click Add message attribute.
Enter a key and a value for the attribute.
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.
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.
Using attributes
You can embed custom attributes as metadata in Pub/Sub messages. Attributes can be text strings or byte strings. The message schema can be represented as follows:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
The PubsubMessage
JSON schema is published as part of the
REST and
RPC
documentation.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp"
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.
Using ordering keys
If messages have the same ordering key and you publish the messages to the same region, subscribers can receive the messages in order. Publishing messages with ordering keys might increase latency. To publish messages to the same region, use a regional endpoint.
You can publish messages with ordering keys using the Cloud Console,
the gcloud
command-line tool, or the Pub/Sub API.
Console
In the Cloud Console, go to the Pub/Sub topics page.
Click the topic ID.
In the Topic details page, click Publish messages.
In the Message body field, enter the message data.
In the Ordering key 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.
Using schema
You can publish messages to topics with schema associated with them. To learn more, see Creating and managing schemas. Messages should be encoded in the schema and format specified when you created the topic.
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.
Avro ProtoBatching messages
The Pub/Sub client libraries batch multiple messages into a single call to the service. Larger batch sizes increase message throughput (rate of messages sent per CPU). The cost of batching is latency for individual messages, which are queued in memory until their corresponding batch is filled and ready to be sent over the network. To minimize latency, batching should be turned off. This is particularly important for applications that publish a single message as part of a request-response sequence. A common example of this pattern is encountered in serverless, event-driven applications using Cloud Functions or App Engine.
Messages can be batched based on request size (in bytes), number of messages, and time. You can override the default settings as shown in this sample:
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.
Retrying requests
Publishing failures are automatically retried, except for errors that do not warrant retries. This sample code demonstrates creating a publisher with custom retry settings (note that not all client libraries support custom retry settings; see the API Reference documentation for your chosen language):
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.
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.
Retry settings control how the Pub/Sub client libraries retry publish requests. The client libraries have any of the following retry settings:
- Initial request timeout: the amount of time before a client library stops waiting for the initial publish request to complete.
- Retry delay: the amount of time after a request times out that a client library waits to retry the request.
- Total timeout: the amount of time before a client library stops retrying publish requests.
To retry publish requests, the initial request timeout must be shorter than the total timeout. For example, if you're using exponential backoff, the client libraries compute the request timeout and retry delay as follows:
- After each publish request, the request timeout increases by the request timeout multiplier, up to the maximum request timeout.
- After each retry, the retry delay increases by the retry delay multiplier, up to the maximum retry delay.
When a client library retries a request and the message has an ordering key, the client library repeatedly retries the request, regardless of the retry settings.
If a non-retryable error occurs, the client library doesn't publish the message and stops publishing other messages with the same ordering key. For example, when a publisher sends a message to a topic that doesn't exist, a non-retryable error occurs. To continue publishing messages with the same ordering key, call a method to resume publishing and then start publishing again.
The following sample shows you how to resume publishing messages with the same ordering key.
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.
Concurrency control
Support for concurrency depends on your programming language. Refer to the API Reference documentation for more information.
The following sample illustrates how to control concurrency in a publisher:
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.
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.