Pub/Sub cannot retrieve the messages after you have acknowledged them. However, sometimes you might find it necessary to replay the acknowledged messages, for example, if you performed an erroneous acknowledgment. Then you can use theSeek feature to mark previously acknowledged messages as unacknowledged, and force Pub/Sub to redeliver those messages. You can also use seek to delete the unacknowledged messages by changing their state to acknowledged.

Seek to asnapshot or seek to atimestamp to replay the messages in a subscription. This guide shows examples of how to replay previously acknowledged Pub/Sub messages using seek.

To follow step-by-step guidance for this task directly in the Google Cloud console, clickGuide me:

Guide me

Before you begin

Complete the following steps before running your pipeline.

Set up your project

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Set up a Google Cloud console project.
Set up a project
Click to:
• Create or select a project.
• Enable the Pub/Sub API for that project.
You can view and manage these resources at any time in theGoogle Cloud console.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Toinitialize the gcloud CLI, run the following command:
gcloudinit
Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console,use Cloud Shell.

Set up a Google Cloud console project.

Set up a project

Click to:

• Create or select a project.
• Enable the Pub/Sub API for that project.

You can view and manage these resources at any time in theGoogle Cloud console.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

Toinitialize the gcloud CLI, run the following command:

gcloudinit

Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console,use Cloud Shell.

Required roles

To complete this quickstart, you need the following Identity and Access Management(IAM) roles.

To get the permissions that you need to complete this quickstart, ask your administrator to grant you the following IAM roles on your project:

• Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
• Pub/Sub Editor (roles/pubsub.editor)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Using thegcloud Command-Line Interface

The easiest way to use gcloud is in theCloud Shell.You can also use the command line toolthat comes with theGoogle Cloud CLI.Setup prerequisites are met automatically for the gcloud CLI if youcreate a brand newCompute Engine machine instance with access scopes including all Cloud APIs and the default Debian image. Thesimplest way to create it is via the Compute Engine UI. For the rest of thisdocument, we will assume that you are using one of these command line tools.

For more information about using gcloud, see thegcloud quickstart.Also see thegcloud pubsub section in thegcloud reference for a complete list of Pub/Subgcloud commands.

Create and Seek to Snapshots

Create a topic and a subscription. For better interactivity, use a shortacknowledgment deadline:

gcloudpubsubtopicscreateseek-demo-topicgcloudpubsubsubscriptionscreateseek-demo-sub--topic=seek-demo-topic--ack-deadline=10

So far, no messages in the subscription have beenacknowledged. Capture this state by creating a snapshot:

gcloudpubsubsnapshotscreatemy-snapshot--subscription=seek-demo-subgcloudpubsubsnapshotslist

Now publish, pull, and acknowledge a message:

gcloudpubsubtopicspublishseek-demo-topic--message'hello, world'gcloudpubsubsubscriptionspull--auto-ackseek-demo-sub

Note that subsequent pulls yield no new messages (some transient duplicates arepossible):

gcloudpubsubsubscriptionspull--auto-ackseek-demo-sub

You can recover the message by seeking the subscription to the snapshot.Note that the message may not be delivered instantly: Pub/Subdoes not guarantee message delivery latency. However, what isguaranteed is that the messages retained inthe snapshot will be eventually delivered at least once:

gcloudpubsubsubscriptionsseekseek-demo-sub--snapshot=my-snapshotgcloudpubsubsubscriptionspullseek-demo-sub--auto-ack

Note that you can seek other subscriptions to the same snapshot, as long asthe subscription's topic is the same as the snapshot's topic:

gcloudpubsubsubscriptionscreateseek-demo-sub2--topic=seek-demo-topic--ack-deadline=10gcloudpubsubsubscriptionsseekseek-demo-sub2--snapshot=my-snapshot

Pulling fromseek-demo-sub2 will now yield messages which were published beforeseek-demo-sub2 was created:

gcloudpubsubsubscriptionspullseek-demo-sub2--auto-ack

When you are done with the snapshot, clean up:

gcloudpubsubsnapshotsdeletemy-snapshot

Seek to a timestamp

Another way to replay messages that have been acknowledged is to seek to atimestamp. To seek to a timestamp, you must first configure the subscription toretain acknowledged messages usingretain-acked-messages. Ifretain-acked-messages is set, Pub/Sub retains acknowledgedmessages for 7 days.

You only need to do this step if you intend to seek to a timestamp, not to asnapshot.

gcloudpubsubsubscriptionsupdateseek-demo-sub--retain-acked-messages

Now publish, pull, and acknowledge a message:

gcloudpubsubtopicspublishseek-demo-topic--message'hello, world'gcloudpubsubsubscriptionspull--auto-ackseek-demo-sub

The next pull should return no messages:

gcloudpubsubsubscriptionspullseek-demo-sub

Now seek the subscription back in time to recover the message.Note that the date arithmetic flags differ between the GNU and BSD (MacOS)versions of the date command:

exportTS_FORMAT=%Y-%m-%dT%H:%M:%SZgcloudpubsubsubscriptionsseekseek-demo-sub--time=$(date-u-d'-10 min'+$TS_FORMAT)

For more information about supported time formats, seegcloud topic datetimes.

A subsequent pull should yield the message again:

gcloudpubsubsubscriptionspull--auto-ackseek-demo-sub

You can also use seek to skip delivery of all messages publishedbefore some point in time, such as the current time. To do this,seek the subscription to the current time to mark as acknowledged allpast messages:

gcloudpubsubtopicspublishseek-demo-topic--message'hello, world'gcloudpubsubsubscriptionsseekseek-demo-sub--time=$(date-u+$TS_FORMAT)

After some propagation delay (~60 seconds), the message will no longerbe delivered. You can check this by repeatedly executing the pull commandwithout acknowledging the message:

gcloudpubsubsubscriptionspullseek-demo-sub

Using the Cloud console

You can create snapshots, or seek to existing snapshots, in the subscriptiondetail page of theCloud console.For snapshot naming rules, seeResource names.

Creating a snapshot

1. In the Google Cloud console, go to thePub/Sub subscriptions page.

   Go to the subscriptions page

2. Select a subscription from the list.

3. ClickCreate snapshot.

4. Enter an ID for the snapshot, then clickCreate to save.

Snapshots can be viewed on thesnapshots page in the Google Cloud console. You can also manage snapshots in thedetails page of an individual topic.

Replaying a subscription

TheReplay messages dialog lets you seek to a previous time point or a saved snapshot. To open the dialog:

1. In the Google Cloud console, go to thePub/Sub subscriptions page.

   Go to the subscriptions page

2. Select a subscription from the list.

3. ClickReplay messages.

4. UnderSeek, select eitherTo a previous time point orTo a snapshot, then select the time point or snapshot to seek to.

5. ClickSeek to replay messages.

Note that additional resources and links are available on thePub/Sub support page.

What's next

SeeReplaying and discarding messages.