Method: projects.snapshots.create

Creates a snapshot from the requested subscription. Snapshots are used in subscriptions.seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

BETA: This feature is part of a beta release. This API might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.

If the snapshot already exists, returns ALREADY_EXISTS. If the requested subscription doesn't exist, returns NOT_FOUND. If the backlog in the subscription is too old -- and the resulting snapshot would expire in less than 1 hour -- then FAILED_PRECONDITION is returned. See also the Snapshot.expire_time field. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription, conforming to the resource name format. The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

HTTP request

PUT https://pubsub.googleapis.com/v1/{name}

Path parameters

Parameters
name

string

Optional user-provided name for this snapshot. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription. Note that for REST API requests, you must specify a name. See the resource name rules. Format is projects/{project}/snapshots/{snap}.

Request body

The request body contains data with the following structure:

JSON representation
{
  "subscription": string,
  "labels": {
    string: string,
    ...
  }
}
Fields
subscription

string

The subscription whose backlog the snapshot retains. Specifically, the created snapshot is guaranteed to retain: (a) The existing backlog on the subscription. More precisely, this is defined as the messages in the subscription's backlog that are unacknowledged upon the successful completion of the snapshots.create request; as well as: (b) Any messages published to the subscription's topic following the successful completion of the snapshots.create request. Format is projects/{project}/subscriptions/{sub}.

labels

map (key: string, value: string)

See Creating and managing labels.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Response body

If successful, the response body contains a newly created instance of Snapshot.

Authorization Scopes

Requires one of the following OAuth scopes:

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

For more information, see the Authentication Overview.

Try it!

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Pub/Sub