snapshots

Creates, updates, deletes, gets or lists a snapshots resource.

Overview

Name	snapshots
Type	Resource
Id	google.pubsub.snapshots

Fields

The following fields are returned by SELECT queries:

projects_topics_snapshots_list

Successful response

Name	Datatype	Description

projects_snapshots_get

Successful response

Name	Datatype	Description
name	string	Optional. The name of the snapshot.
expireTime	string (google-datetime)	Optional. The snapshot is guaranteed to exist up until this time. A newly-created snapshot expires no later than 7 days from the time of its creation. Its exact lifetime is determined at creation by the existing backlog in the source subscription. Specifically, the lifetime of the snapshot is 7 days - (age of oldest unacked message in the subscription). For example, consider a subscription whose oldest unacked message is 3 days old. If a snapshot is created from this subscription, the snapshot -- which will always capture this 3-day-old backlog as long as the snapshot exists -- will expire in 4 days. The service will refuse to create a snapshot that would expire in less than 1 hour after creation.
labels	object	Optional. See [Creating and managing labels] (https://cloud.google.com/pubsub/docs/labels).
topic	string	Optional. The name of the topic from which this snapshot is retaining messages.

projects_snapshots_list

Successful response

Name	Datatype	Description
name	string	Optional. The name of the snapshot.
expireTime	string (google-datetime)	Optional. The snapshot is guaranteed to exist up until this time. A newly-created snapshot expires no later than 7 days from the time of its creation. Its exact lifetime is determined at creation by the existing backlog in the source subscription. Specifically, the lifetime of the snapshot is 7 days - (age of oldest unacked message in the subscription). For example, consider a subscription whose oldest unacked message is 3 days old. If a snapshot is created from this subscription, the snapshot -- which will always capture this 3-day-old backlog as long as the snapshot exists -- will expire in 4 days. The service will refuse to create a snapshot that would expire in less than 1 hour after creation.
labels	object	Optional. See [Creating and managing labels] (https://cloud.google.com/pubsub/docs/labels).
topic	string	Optional. The name of the topic from which this snapshot is retaining messages.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
projects_topics_snapshots_list	select	projectsId, topicsId	pageSize, pageToken	Lists the names of the snapshots on this topic. Snapshots are used in 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.
projects_snapshots_get	select	projectsId, snapshotsId		Gets the configuration details of a snapshot. Snapshots are used in 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.
projects_snapshots_list	select	projectsId	pageSize, pageToken	Lists the existing snapshots. Snapshots are used in 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.
projects_snapshots_patch	update	projectsId, snapshotsId		Updates an existing snapshot by updating the fields specified in the update mask. Snapshots are used in 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.
projects_snapshots_delete	delete	projectsId, snapshotsId		Removes an existing snapshot. Snapshots are used in [Seek] (https://cloud.google.com/pubsub/docs/replay-overview) 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. When the snapshot is deleted, all messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified.
projects_snapshots_create	exec	projectsId, snapshotsId		Creates a snapshot from the requested subscription. Snapshots are used in 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. 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] (https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names). The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
projectsId	string
snapshotsId	string
topicsId	string
pageSize	integer (int32)
pageToken	string

SELECT examples

projects_topics_snapshots_list

Lists the names of the snapshots on this topic. Snapshots are used in 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.

SELECT
*
FROM google.pubsub.snapshots
WHERE projectsId = '{{ projectsId }}' -- required
AND topicsId = '{{ topicsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

projects_snapshots_get

Gets the configuration details of a snapshot. Snapshots are used in 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.

SELECT
name,
expireTime,
labels,
topic
FROM google.pubsub.snapshots
WHERE projectsId = '{{ projectsId }}' -- required
AND snapshotsId = '{{ snapshotsId }}' -- required;

projects_snapshots_list

Lists the existing snapshots. Snapshots are used in 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.

SELECT
name,
expireTime,
labels,
topic
FROM google.pubsub.snapshots
WHERE projectsId = '{{ projectsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}';

UPDATE examples

projects_snapshots_patch

Updates an existing snapshot by updating the fields specified in the update mask. Snapshots are used in 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.

UPDATE google.pubsub.snapshots
SET 
data__snapshot = '{{ snapshot }}',
data__updateMask = '{{ updateMask }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND snapshotsId = '{{ snapshotsId }}' --required
RETURNING
name,
expireTime,
labels,
topic;

DELETE examples

projects_snapshots_delete

Removes an existing snapshot. Snapshots are used in [Seek] (https://cloud.google.com/pubsub/docs/replay-overview) 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. When the snapshot is deleted, all messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified.

DELETE FROM google.pubsub.snapshots
WHERE projectsId = '{{ projectsId }}' --required
AND snapshotsId = '{{ snapshotsId }}' --required;

Lifecycle Methods

projects_snapshots_create

Creates a snapshot from the requested subscription. Snapshots are used in 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. 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] (https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names). The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

EXEC google.pubsub.snapshots.projects_snapshots_create 
@projectsId='{{ projectsId }}' --required, 
@snapshotsId='{{ snapshotsId }}' --required 
@@json=
'{
"subscription": "{{ subscription }}", 
"labels": "{{ labels }}"
}';