Working with Pub/Sub

Pub/Sub is a fully-managed real-time messaging service that allows you to send and receive messages between independent applications. This page shows how to manage Pub/Sub using Cloud Tools for PowerShell. It walks through a simple example of creating a topic, publishing messages to the topic, creating a subscription to the topic, and pulling messages from the topic to the subscription.

Read the Cloud Tools for PowerShell cmdlet reference to learn more about Pub/Sub cmdlets. To learn more about Pub/Sub in general, read the Overview of Pub/Sub.

Creating a topic

The publisher application creates and sends messages to a topic. You can call the New‑GcpsTopic cmdlet to create an instance in a particular topic. If your active gcloud configuration has a project, you don't have to use the -Project parameter.

# Creates topic "my-topic" in the default project.
New-GcpsTopic -Topic "my-topic"

Publishing messages to a topic

To publish messages to a topic, you can use the Publish‑GcpsMessage cmdlet.

# Publishes the message with data "This is a test" to topic "my-topic".
Publish-GcpsMessage -Data "This is a test" -Topic "my-topic"

To publish multiple messages to the same topic with a single request, you can use the New‑GcpsMessage cmdlet to create an array of messages and pass that to the Publish‑GcpsMessage cmdlet.

# Creates two messages.
$messageOne = New-GcpsMessage -Data "This is a test"
$messageTwo = New-GcpsMessage -Data "Data" -Attributes @{"key" = "value"}

# Publish the messages to topic "my-topic".
Publish-GcpsMessage -Message @($messageOne, $messageTwo) -Topic "my-topic"

Creating a subscription to a topic

The subscriber application creates a subscription to a topic to receive messages from it. You can call the New‑GcpsSubscription cmdlet to create an instance in a particular topic. If your active gcloud configuration has a project, you don't have to use the -Project parameter.

By default, the subscription created is a pull subscription, which means the subscriber will pull the messages from the topic. You can create a push subscription (Pub/Sub will push messages to the subscriber's chosen endpoint) with -PushEndpoint.

# Creates pull subscription "pull-subscription" to topic "my-topic" in the default project.
New-GcpsSubscription -Topic "my-topic" -Subscription "pull-subscription"

# Creates push subscription "push-subscription" to topic "my-topic".
New-GcpsSubscription -Topic "my-topic" `
                     -Subscription "push-subscription" `
                     -PushEndpoint "http://www.example.com"

Pulling messages for the subscription

To pull messages for the subscription, you can use the Get‑GcpsMessage cmdlet. By default, the cmdlet will block until at least one message is retrieved. To prevent blocking, use the parameter -ReturnImmediately. The cmdlet can also automatically send an acknowledgement for every retrieved message if you use the parameter -AutoAck. If not, you will have to use the Send‑GcpsAck cmdlet to send the acknowledgement. Unacknowledged messages become available again for pulling after the acknowledgement deadline of the message expires.

# Pulls messages from subscription "my-subscription" and sends out acknowledgement automatically.
Get-GcpsMessage -Subscription "my-subscription" -AutoAck

# Pulls messages from subscription "my-subscription" and sends out acknowledgement with Send-GcpsAck.
$messages = Get-GcpsMessage -Subscription "my-subscription"
Send-GcpsAck -InputObject $messages