Cloud Pub/Sub is a fully managed real-time messaging service that allows you to send and receive messages between independent applications. This tutorial gives a brief introduction to Cloud Pub/Sub's command-line interface using the gcloud command.

Project setup

Google Cloud Platform organises resources into projects. This allows you to collect all the related resources for a single application in one place.

Cloud Pub/Sub needs a project to set up messages.

Select a project, or create a new one

Create your first topic

Open Google Cloud Shell

Cloud Shell is a built-in command-line tool for the console. You're going to use Cloud Shell to set up Cloud Pub/Sub.

Open Cloud Shell by clicking the 

 Activate Cloud Shell button in the navigation bar in the upper-right corner of the console.

Create a topic

A topic is a named resource to which you will send messages. Create your first topic with the following command:

Add a subscription

To receive messages, you need to create subscriptions. A subscription needs to have a corresponding topic. Create your first subscription with the following command:

This command creates a subscription named my-sub attached to the topic my-topic. All the messages published to my-topic will be delivered to this subscription.

You may notice the --ack-deadline=60 option. ack-deadline stands for Acknowledgement deadline. This new subscription has an Acknowledgement deadline of 60 seconds. We will explain this a bit later.

List topics and subscriptions

Before sending your first message, check if the topic and the subscription have been successfully created. List your topic and subscription using the following command:

(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub topics create my-topic
Created topic [projects/angular-theorem-281823/topics/my-topic].
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions create \
>     my-sub --topic my-topic \
>     --ack-deadline=60
Created subscription [projects/angular-theorem-281823/subscriptions/my-sub].
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub topics list
---
name: projects/angular-theorem-281823/topics/my-topic
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions list
---
ackDeadlineSeconds: 60
expirationPolicy:
  ttl: 2678400s
messageRetentionDuration: 604800s
name: projects/angular-theorem-281823/subscriptions/my-sub
pushConfig: {}
topic: projects/angular-theorem-281823/topics/my-topic
(env) jyan@cloudshell:~ (angular-theorem-281823)$

Publish messages to the topic

Send two messages with the following commands:

Each of these commands sends a message. The first message is hello and the second is goodbye. When you successfully publish a message, you should see the messageId returned from the server. This is a unique ID automatically assigned by the server to each message.

(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub topics publish \
>     my-topic --message hello
messageIds:
- '1268536160021218'
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub topics publish \
>     my-topic --message goodbye
messageIds:
- '1268518135841445'
(env) jyan@cloudshell:~ (angular-theorem-281823)$

Pull messages from the subscription

Pull messages

Now, pull the messages with the following command:

Note: Cloud Pub/Sub doesn't guarantee the order of the messages. It is also possible that you saw only one message. In that case, try running the same command several times until you see the other message.

Acknowledge and acknowledgement deadline

After you pull a message and correctly process it, you must notify Cloud Pub/Sub that you've successfully received the message. This action is called acknowledge.

You may have noticed the --auto-ack flag passed along with the pull command. The --auto-ack flag automatically pulls the message and acknowledges it.

(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions pull \
>     --auto-ack --limit=2 my-sub
┌─────────┬──────────────────┬────────────┬──────────────────┐
│   DATA  │    MESSAGE_ID    │ ATTRIBUTES │ DELIVERY_ATTEMPT │
├─────────┼──────────────────┼────────────┼──────────────────┤
│ hello   │ 1268536160021218 │            │                  │
│ goodbye │ 1268518135841445 │            │                  │
└─────────┴──────────────────┴────────────┴──────────────────┘
(env) jyan@cloudshell:~ (angular-theorem-281823)$

Manual acknowledgement

Send a new message

Send a new message with the following command:

Pull messages again

Pull the messages with:

This should display the thanks message, as well as MESSAGE_ID and ACK_ID. The ACK_ID is another ID that you can use for acknowledging the message.

Acknowledge the message

After you pull a message, you need to acknowledge the message before the acknowledgement deadline has passed. For example, if a subscription is configured to have a 60-second acknowledgement deadline, as we did in this tutorial, you need to acknowledge the message within 60 seconds after you pulled the message. Otherwise, Cloud Pub/Sub will resend the message.

Acknowledge the message with the following command (replace the ACK_ID with the real one by copy/paste):

(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub topics publish \
>     my-topic --message thanks
messageIds:
- '1268559392922740'
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions pull \
>     my-sub
┌────────┬──────────────────┬────────────┬──────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  DATA  │    MESSAGE_ID    │ ATTRIBUTES │ DELIVERY_ATTEMPT │                                                                                          ACK_ID                                                                                          │
├────────┼──────────────────┼────────────┼──────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ thanks │ 1268559392922740 │            │                  │ ISE-MD5FU0RQBhYsXUZIUTcZCGhRDk9eIz81IChFEgIHTwIoXXkxSzdBWXxoUQ0Zcn1gcmgMR1RREFJ2V1EaB2hObXUlcQwbdHVkcGNZGgMLR1F5W1szlIbwprWEwT8DSUX44r-dJiH0oq4tZiU9XhJLLD5-MDxFQV5AEkw7CURJUytDCypYEU4E │
└────────┴──────────────────┴────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
(env) jyan@cloudshell:~ (angular-theorem-281823)$

(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions ack \
>     my-sub --ack-ids ACK_ID
ERROR: (gcloud.pubsub.subscriptions.ack) INVALID_ARGUMENT: You have passed an invalid ack ID to the service (ack_id=ACK_ID).
(env) jyan@cloudshell:~ (angular-theorem-281823)$ gcloud pubsub subscriptions ack     my-sub --ack-ids ISE-MD5FU0RQBhYsXUZIUTcZCGhRDk9eIz81IChFEgIHTwIoXXkxSzdBWXxoUQ0Zcn1gcmgMR1RREFJ2V1EaB2hObXUlcQwbdHVkcGNZGgMLR1F5W1szlIbwprWEwT8DSUX44r-dJiH0oq4tZiU9XhJLLD5-MDxFQV5AEkw7CURJUytDCypYEU4E
Acked the messages with the following ackIds: [ISE-MD5FU0RQBhYsXUZIUTcZCGhRDk9eIz81IChFEgIHTwIoXXkxSzdBWXxoUQ0Zcn1gcmgMR1RREFJ2V1EaB2hObXUlcQwbdHVkcGNZGgMLR1F5W1szlIbwprWEwT8DSUX44r-dJiH0oq4tZiU9XhJLLD5-MDxFQV5AEkw7CURJUytDCypYEU4E]
{}
(env) jyan@cloudshell:~ (angular-theorem-281823)$

See the topic and the subscription in Pub/Sub UI

This concludes the gcloud command line tutorial, but let's look at the UI on the Google Cloud Console before finishing the tutorial.

You can also see the topics and subscriptions in the Pub/Sub section.

Navigate to the Pub/Sub section

Open the menu on the left-hand side of the console.

Then, select the Pub/Sub section.

 

Pub/Sub

 

The UI also allows you to create and manage topics and subscriptions.

Delete the topic

Tick the tick box next to the topic that you created and click the Delete button to permanently delete the topic.