Method: admin.projects.locations.subscriptions.seek

Performs an out-of-band seek for a subscription to a specified target, which may be timestamps or named positions within the message backlog. Seek translates these targets to cursors for each partition and orchestrates subscribers to start consuming messages from these seek cursors.

If an operation is returned, the seek has been registered and subscribers will eventually receive messages from the seek cursors (i.e. eventual consistency), as long as they are using a minimum supported client library version and not a system that tracks cursors independently of Pub/Sub Lite (e.g. Apache Beam, Dataflow, Spark). The seek operation will fail for unsupported clients.

If clients would like to know when subscribers react to the seek (or not), they can poll the operation. The seek operation will succeed and complete once subscribers are ready to receive messages from the seek cursors for all partitions of the topic. This means that the seek operation will not complete until all subscribers come online.

If the previous seek operation has not yet completed, it will be aborted and the new invocation of seek will supersede it.

HTTP request

POST https://{endpoint}/v1/admin/{name=projects/*/locations/*/subscriptions/*}:seek

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The name of the subscription to seek.

Authorization requires the following IAM permission on the specified resource name:

  • pubsublite.subscriptions.seek

Request body

The request body contains data with the following structure:

JSON representation 
{

  // Union field target can be only one of the following:
  "namedTarget": enum (NamedTarget),
  "timeTarget": {
    object (TimeTarget)
  }
  // End of list of possible types for union field target.
}
Fields
Union field target. The target to seek to. Must be set. target can be only one of the following:
namedTarget

enum (NamedTarget)

Seek to a named position with respect to the message backlog.
timeTarget

object (TimeTarget)

Seek to the first message whose publish or event time is greater than or equal to the specified query time. If no such message can be located, will seek to the end of the message backlog.

Response body

If successful, the response body contains an instance of Operation.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

NamedTarget

A named position with respect to the message backlog.

Enums
NAMED_TARGET_UNSPECIFIED Unspecified named target. Do not use.
TAIL Seek to the oldest retained message.
HEAD Seek past all recently published messages, skipping the entire message backlog.