Performs subscription administrative operations in Cloud Pub/Sub. More...

#include <google/cloud/pubsub/subscription_admin_client.h>

Public Member Functions
	SubscriptionAdminClient (std::shared_ptr< SubscriptionAdminConnection > connection)

	SubscriptionAdminClient ()=delete
	The default constructor is deleted. More...

StatusOr< google::pubsub::v1::Subscription >	CreateSubscription (Topic const &topic, Subscription const &subscription, SubscriptionBuilder builder={})
	Creates a new subscription in Cloud Pub/Sub. More...

StatusOr< google::pubsub::v1::Subscription >	GetSubscription (Subscription subscription)
	Gets the metadata for an existing Cloud Pub/Sub subscription. More...

StatusOr< google::pubsub::v1::Subscription >	UpdateSubscription (Subscription const &subscription, SubscriptionBuilder builder)
	Updates an existing subscription in Cloud Pub/Sub. More...

ListSubscriptionsRange	ListSubscriptions (std::string const &project_id)
	Lists all the subscriptions for a given project id. More...

Status	DeleteSubscription (Subscription subscription)
	Deletes an existing subscription in Cloud Pub/Sub. More...

Status	ModifyPushSubscription (Subscription const &subscription, PushConfigBuilder builder)
	Modifies an existing subscription's push configuration. More...

StatusOr< google::pubsub::v1::Snapshot >	CreateSnapshot (Subscription const &subscription, SnapshotBuilder builder={})
	Creates a new snapshot for a subscription with a server-assigned name. More...

StatusOr< google::pubsub::v1::Snapshot >	CreateSnapshot (Subscription const &subscription, Snapshot const &snapshot, SnapshotBuilder builder={})
	Creates a new snapshot for a subscription with a given name. More...

StatusOr< google::pubsub::v1::Snapshot >	GetSnapshot (Snapshot const &snapshot)
	Gets information about an existing snapshot. More...

StatusOr< google::pubsub::v1::Snapshot >	UpdateSnapshot (Snapshot const &snapshot, SnapshotBuilder builder)
	Updates an existing snapshot. More...

ListSnapshotsRange	ListSnapshots (std::string const &project_id)
	Lists all the snapshots for a given project id. More...

Status	DeleteSnapshot (Snapshot const &snapshot)
	Deletes a snapshot. More...

StatusOr< google::pubsub::v1::SeekResponse >	Seek (Subscription const &subscription, std::chrono::system_clock::time_point timestamp)
	Seeks a subscription to its state at `timestamp`. More...

StatusOr< google::pubsub::v1::SeekResponse >	Seek (Subscription const &subscription, Snapshot const &snapshot)
	Seeks a subscription to its state at `snapshot`. More...

Detailed Description

Performs subscription administrative operations in Cloud Pub/Sub.

Applications use this class to perform subscription administrative operations on Cloud Pub/Sub.

Performance: SubscriptionAdminClient objects are relatively cheap to create, copy, and move. However, each SubscriptionAdminClient object must be created with a std::shared_ptr<SubscriptionAdminConnection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeSubscriptionAdminConnection() function and the SubscriptionAdminConnection interface for more details.

Thread Safety: Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.

Error Handling: This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. Please consult the StatusOr<T> documentation for more details.

Definition at line 60 of file subscription_admin_client.h.

Constructor & Destructor Documentation

◆ SubscriptionAdminClient() [1/2]

google::cloud::pubsub::SubscriptionAdminClient::SubscriptionAdminClient ( std::shared_ptr< SubscriptionAdminConnection > connection )

explicit

◆ SubscriptionAdminClient() [2/2]

google::cloud::pubsub::SubscriptionAdminClient::SubscriptionAdminClient ( )

delete

The default constructor is deleted.

Use SubscriberClient(std::shared_ptr<SubscriberConnection>)

Member Function Documentation

◆ CreateSnapshot() [1/2]

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::SubscriptionAdminClient::CreateSnapshot	(	Subscription const &	subscription,
		Snapshot const &	snapshot,
		SnapshotBuilder	builder = `{}`
	)

inline

Creates a new snapshot for a subscription with a given name.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id, std::string const& snapshot_id) {

auto snapshot = client.CreateSnapshot(

pubsub::Subscription(project_id, subscription_id),

pubsub::Snapshot(project_id, std::move(snapshot_id)));

if (snapshot.status().code() == google::cloud::StatusCode::kAlreadyExists) {

std::cout << "The snapshot already exists\n";

return;

}

if (!snapshot.ok()) throw std::runtime_error(snapshot.status().message());

std::cout << "The snapshot was successfully created: "

<< snapshot->DebugString() << "\n";

}

google::cloud::StatusCode::kAlreadyExists
@ kAlreadyExists

Parameters

subscription	the name of the subscription
snapshot	the name of the snapshot
builder	additional configuration for the snapshot, e.g., labels

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 220 of file subscription_admin_client.h.

◆ CreateSnapshot() [2/2]

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::SubscriptionAdminClient::CreateSnapshot	(	Subscription const &	subscription,
		SnapshotBuilder	builder = `{}`
	)

inline

Creates a new snapshot for a subscription with a server-assigned name.

Idempotency: This is not an idempotent operation, repeated calls would create multiple snapshots with different names assigned by the service, and therefore it is never retried.

Parameters

subscription	the name of the subscription
builder	additional configuration for the snapshot, e.g., labels

Definition at line 197 of file subscription_admin_client.h.

◆ CreateSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::SubscriptionAdminClient::CreateSubscription	(	Topic const &	topic,
		Subscription const &	subscription,
		SubscriptionBuilder	builder = `{}`
	)

inline

Creates a new subscription in Cloud Pub/Sub.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried. It might return a status code of kAlreadyExists as a consequence of retrying a successful (but reported as failed) request.

Example: Create a Pull Subscription: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& topic_id, std::string const& subscription_id) {

auto sub = client.CreateSubscription(

pubsub::Topic(project_id, std::move(topic_id)),

pubsub::Subscription(project_id, std::move(subscription_id)));

if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {

std::cout << "The subscription already exists\n";

return;

}

if (!sub) throw std::runtime_error(sub.status().message());

std::cout << "The subscription was successfully created: "

<< sub->DebugString() << "\n";

}

Example: Create a Push Subscription: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& topic_id, std::string const& subscription_id,

std::string const& endpoint) {

auto sub = client.CreateSubscription(

pubsub::Topic(project_id, std::move(topic_id)),

pubsub::Subscription(project_id, std::move(subscription_id)),

pubsub::SubscriptionBuilder{}.set_push_config(

pubsub::PushConfigBuilder{}.set_push_endpoint(endpoint)));

if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {

std::cout << "The subscription already exists\n";

return;

}

if (!sub) throw std::runtime_error(sub.status().message());

std::cout << "The subscription was successfully created: "

<< sub->DebugString() << "\n";

}

Parameters

topic	the topic that the subscription will attach to
subscription	the name for the subscription
builder	any additional configuration for the subscription

Definition at line 91 of file subscription_admin_client.h.

◆ DeleteSnapshot()

Status google::cloud::pubsub::SubscriptionAdminClient::DeleteSnapshot ( Snapshot const & snapshot )

inline

Deletes a snapshot.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id, std::string const& snapshot_id) {

auto snapshot = client.CreateSnapshot(

pubsub::Subscription(project_id, subscription_id),

pubsub::Snapshot(project_id, std::move(snapshot_id)));

if (snapshot.status().code() == google::cloud::StatusCode::kAlreadyExists) {

std::cout << "The snapshot already exists\n";

return;

}

if (!snapshot.ok()) throw std::runtime_error(snapshot.status().message());

std::cout << "The snapshot was successfully created: "

<< snapshot->DebugString() << "\n";

}

Parameters

snapshot the name of the snapshot

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 298 of file subscription_admin_client.h.

◆ DeleteSubscription()

Status google::cloud::pubsub::SubscriptionAdminClient::DeleteSubscription ( Subscription subscription )

inline

Deletes an existing subscription in Cloud Pub/Sub.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried. It might return a status code of kNotFound as a consequence of retrying a successful (but reported as failed) request.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id) {

auto status = client.DeleteSubscription(pubsub::Subscription(

std::move(project_id), std::move(subscription_id)));

// Note that kNotFound is a possible result when the library retries.

if (status.code() == google::cloud::StatusCode::kNotFound) {

std::cout << "The subscription was not found\n";

return;

}

if (!status.ok()) throw std::runtime_error(status.message());

std::cout << "The subscription was successfully deleted\n";

}

google::cloud::StatusCode::kNotFound
@ kNotFound

Parameters

subscription the name of the subscription to be deleted.

Definition at line 158 of file subscription_admin_client.h.

◆ GetSnapshot()

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::SubscriptionAdminClient::GetSnapshot ( Snapshot const & snapshot )

inline

Gets information about an existing snapshot.

Idempotency: This is a read-only operation and therefore always idempotent and retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& snapshot_id) {

auto response = client.GetSnapshot(

pubsub::Snapshot(std::move(project_id), std::move(snapshot_id)));

if (!response.ok()) throw std::runtime_error(response.status().message());

std::cout << "The snapshot details are: " << response->DebugString()

<< "\n";

}

Parameters

snapshot the name of the snapshot

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 241 of file subscription_admin_client.h.

◆ GetSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::SubscriptionAdminClient::GetSubscription ( Subscription subscription )

inline

Gets the metadata for an existing Cloud Pub/Sub subscription.

Idempotency: This is a read-only operation and therefore always idempotent and retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id) {

auto sub = client.GetSubscription(

pubsub::Subscription(project_id, std::move(subscription_id)));

if (!sub) throw std::runtime_error(sub.status().message());

std::cout << "The subscription exists and its metadata is: "

<< sub->DebugString() << "\n";

}

Definition at line 107 of file subscription_admin_client.h.

◆ ListSnapshots()

ListSnapshotsRange google::cloud::pubsub::SubscriptionAdminClient::ListSnapshots ( std::string const & project_id )

inline

Lists all the snapshots for a given project id.

Idempotency: This is a read-only operation and therefore always idempotent and retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id) {

std::cout << "Snapshot list for project " << project_id << ":\n";

for (auto const& snapshot : client.ListSnapshots(project_id)) {

if (!snapshot) throw std::runtime_error(snapshot.status().message());

std::cout << "Snapshot Name: " << snapshot->name() << "\n";

}

}

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 279 of file subscription_admin_client.h.

◆ ListSubscriptions()

ListSubscriptionsRange google::cloud::pubsub::SubscriptionAdminClient::ListSubscriptions ( std::string const & project_id )

inline

Lists all the subscriptions for a given project id.

Idempotency: This is a read-only operation and therefore always idempotent and retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id) {

int count = 0;

for (auto const& subscription : client.ListSubscriptions(project_id)) {

if (!subscription)

throw std::runtime_error(subscription.status().message());

std::cout << "Subscription Name: " << subscription->name() << "\n";

++count;

}

if (count == 0) {

std::cout << "No subscriptions found in project " << project_id << "\n";

}

}

Definition at line 140 of file subscription_admin_client.h.

◆ ModifyPushSubscription()

Status google::cloud::pubsub::SubscriptionAdminClient::ModifyPushSubscription	(	Subscription const &	subscription,
		PushConfigBuilder	builder
	)

inline

Modifies an existing subscription's push configuration.

This can change a push subscription into a pull subscription (by setting an empty push config), change the push endpoint, or change a pull subscription into a push config.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id, std::string const& endpoint) {

auto status = client.ModifyPushSubscription(

pubsub::Subscription(project_id, std::move(subscription_id)),

pubsub::PushConfigBuilder{}.set_push_endpoint(endpoint));

if (!status.ok()) throw std::runtime_error(status.message());

std::cout << "The subscription push configuration was successfully"

<< " modified\n";

}

Parameters

subscription	the name of the subscription to be modified.
builder	a description of the changes to be made.

Definition at line 179 of file subscription_admin_client.h.

◆ Seek() [1/2]

StatusOr<google::pubsub::v1::SeekResponse> google::cloud::pubsub::SubscriptionAdminClient::Seek	(	Subscription const &	subscription,
		Snapshot const &	snapshot
	)

Seeks a subscription to its state at snapshot.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id, std::string const& seconds) {

auto response =

client.Seek(pubsub::Subscription(project_id, subscription_id),

std::chrono::system_clock::now() -

std::chrono::seconds(std::stoi(seconds)));

if (!response.ok()) throw std::runtime_error(response.status().message());

std::cout << "The subscription seek was successful: "

<< response->DebugString() << "\n";

}

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's Seek() functionality.

◆ Seek() [2/2]

StatusOr<google::pubsub::v1::SeekResponse> google::cloud::pubsub::SubscriptionAdminClient::Seek	(	Subscription const &	subscription,
		std::chrono::system_clock::time_point	timestamp
	)

Seeks a subscription to its state at timestamp.

Messages retained in the subscription that were published before timestamp are marked as acknowledged, while messages published after timestamp are marked as unacknowledged.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id, std::string const& seconds) {

auto response =

client.Seek(pubsub::Subscription(project_id, subscription_id),

std::chrono::system_clock::now() -

std::chrono::seconds(std::stoi(seconds)));

if (!response.ok()) throw std::runtime_error(response.status().message());

std::cout << "The subscription seek was successful: "

<< response->DebugString() << "\n";

}

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's Seek() functionality.

◆ UpdateSnapshot()

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::SubscriptionAdminClient::UpdateSnapshot	(	Snapshot const &	snapshot,
		SnapshotBuilder	builder
	)

inline

Updates an existing snapshot.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string snapshot_id) {

auto snap = client.UpdateSnapshot(

pubsub::Snapshot(project_id, std::move(snapshot_id)),

pubsub::SnapshotBuilder{}.add_label("samples-cpp", "gcp"));

if (!snap.ok()) return; // TODO(#4792) - emulator lacks UpdateSnapshot()

std::cout << "The snapshot was successfully updated: "

<< snap->DebugString() << "\n";

}

Parameters

snapshot	the name of the snapshot
builder	the changes applied to the snapshot

See also: https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 261 of file subscription_admin_client.h.

◆ UpdateSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::SubscriptionAdminClient::UpdateSubscription	(	Subscription const &	subscription,
		SubscriptionBuilder	builder
	)

inline

Updates an existing subscription in Cloud Pub/Sub.

Idempotency: This operation is idempotent, the state of the system is the same after one or several calls, and therefore it is always retried.

Example: namespace pubsub = ::google::cloud::pubsub;

[](pubsub::SubscriptionAdminClient client, std::string const& project_id,

std::string const& subscription_id) {

auto s = client.UpdateSubscription(

pubsub::Subscription(project_id, std::move(subscription_id)),

pubsub::SubscriptionBuilder{}.set_ack_deadline(

std::chrono::seconds(60)));

if (!s) throw std::runtime_error(s.status().message());

std::cout << "The subscription has been updated to: " << s->DebugString()

<< "\n";

}

Parameters

subscription	the name for the subscription
builder	any additional configuration for the subscription

Definition at line 125 of file subscription_admin_client.h.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SubscriptionAdminClient() [1/2]

◆ SubscriptionAdminClient() [2/2]

Member Function Documentation

◆ CreateSnapshot() [1/2]

◆ CreateSnapshot() [2/2]

◆ CreateSubscription()

◆ DeleteSnapshot()

◆ DeleteSubscription()

◆ GetSnapshot()

◆ GetSubscription()

◆ ListSnapshots()

◆ ListSubscriptions()

◆ ModifyPushSubscription()

◆ Seek() [1/2]

◆ Seek() [2/2]

◆ UpdateSnapshot()

◆ UpdateSubscription()