google::cloud::pubsub::SubscriptionAdminClient Class Reference

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, Options opts={})
	SubscriptionAdminClient ()=delete
	The default constructor is deleted. More...
StatusOr< google::pubsub::v1::Subscription >	CreateSubscription (Topic const &topic, Subscription const &subscription, SubscriptionBuilder builder={}, Options opts={})
	Creates a new subscription in Cloud Pub/Sub. More...
StatusOr< google::pubsub::v1::Subscription >	GetSubscription (Subscription subscription, Options opts={})
	Gets the metadata for an existing Cloud Pub/Sub subscription. More...
StatusOr< google::pubsub::v1::Subscription >	UpdateSubscription (Subscription const &subscription, SubscriptionBuilder builder, Options opts={})
	Updates an existing subscription in Cloud Pub/Sub. More...
ListSubscriptionsRange	ListSubscriptions (std::string const &project_id, Options opts={})
	Lists all the subscriptions for a given project id. More...
Status	DeleteSubscription (Subscription subscription, Options opts={})
	Deletes an existing subscription in Cloud Pub/Sub. More...
Status	ModifyPushSubscription (Subscription const &subscription, PushConfigBuilder builder, Options opts={})
	Modifies an existing subscription's push configuration. More...
StatusOr< google::pubsub::v1::Snapshot >	CreateSnapshot (Subscription const &subscription, SnapshotBuilder builder={}, Options opts={})
	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={}, Options opts={})
	Creates a new snapshot for a subscription with a given name. More...
StatusOr< google::pubsub::v1::Snapshot >	GetSnapshot (Snapshot const &snapshot, Options opts={})
	Gets information about an existing snapshot. More...
StatusOr< google::pubsub::v1::Snapshot >	UpdateSnapshot (Snapshot const &snapshot, SnapshotBuilder builder, Options opts={})
	Updates an existing snapshot. More...
ListSnapshotsRange	ListSnapshots (std::string const &project_id, Options opts={})
	Lists all the snapshots for a given project id. More...
Status	DeleteSnapshot (Snapshot const &snapshot, Options opts={})
	Deletes a snapshot. More...
StatusOr< google::pubsub::v1::SeekResponse >	Seek (Subscription const &subscription, std::chrono::system_clock::time_point timestamp, Options opts={})
	Seeks a subscription to its state at timestamp. More...
StatusOr< google::pubsub::v1::SeekResponse >	Seek (Subscription const &subscription, Snapshot const &snapshot, Options opts={})
	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, Options  opts = {}  )

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 = {}, Options  opts = {}  )

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";
  }

Parameters

subscription	the name of the subscription
snapshot	the name of the snapshot
builder	additional configuration for the snapshot, e.g., labels
opts	Override the class-level options, such as retry and backoff policies.

See also

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

Definition at line 253 of file subscription_admin_client.h.

CreateSnapshot() [2/2]

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

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
opts	Override the class-level options, such as retry and backoff policies.

Definition at line 225 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 = {}, Options  opts = {}  )

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";
  }

Example: Create a BigQuery 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& table_id) {
    auto sub = client.CreateSubscription(
        pubsub::Topic(project_id, std::move(topic_id)),
        pubsub::Subscription(project_id, std::move(subscription_id)),
        pubsub::SubscriptionBuilder{}.set_bigquery_config(
            pubsub::BigQueryConfigBuilder{}.set_table(table_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";
  }

Parameters

topic	the topic that the subscription will attach to
subscription	the name for the subscription
builder	any additional configuration for the subscription
opts	Override the class-level options, such as retry and backoff policies.

Definition at line 97 of file subscription_admin_client.h.

DeleteSnapshot()

Status google::cloud::pubsub::SubscriptionAdminClient::DeleteSnapshot ( Snapshot const &  snapshot, Options  opts = {}  )

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
opts	Override the class-level options, such as retry and backoff policies.

See also

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

Definition at line 347 of file subscription_admin_client.h.

DeleteSubscription()

Status google::cloud::pubsub::SubscriptionAdminClient::DeleteSubscription ( Subscription  subscription, Options  opts = {}  )

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";
  }

Parameters

subscription	the name of the subscription to be deleted.
opts	Override the class-level options, such as retry and backoff policies.

Definition at line 178 of file subscription_admin_client.h.

GetSnapshot()

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::SubscriptionAdminClient::GetSnapshot ( Snapshot const &  snapshot, Options  opts = {}  )

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
opts	Override the class-level options, such as retry and backoff policies.

See also

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

Definition at line 278 of file subscription_admin_client.h.

GetSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::SubscriptionAdminClient::GetSubscription ( Subscription  subscription, Options  opts = {}  )

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 115 of file subscription_admin_client.h.

ListSnapshots()

ListSnapshotsRange google::cloud::pubsub::SubscriptionAdminClient::ListSnapshots ( std::string const &  project_id, Options  opts = {}  )

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 323 of file subscription_admin_client.h.

ListSubscriptions()

ListSubscriptionsRange google::cloud::pubsub::SubscriptionAdminClient::ListSubscriptions ( std::string const &  project_id, Options  opts = {}  )

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 155 of file subscription_admin_client.h.

ModifyPushSubscription()

Status google::cloud::pubsub::SubscriptionAdminClient::ModifyPushSubscription ( Subscription const &  subscription, PushConfigBuilder  builder, Options  opts = {}  )

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.
opts	Override the class-level options, such as retry and backoff policies.

Definition at line 203 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,
		Options	opts = {}
	)

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,
		Options	opts = {}
	)

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, Options  opts = {}  )

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
opts	Override the class-level options, such as retry and backoff policies.

See also

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

Definition at line 303 of file subscription_admin_client.h.

UpdateSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::SubscriptionAdminClient::UpdateSubscription ( Subscription const &  subscription, SubscriptionBuilder  builder, Options  opts = {}  )

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
opts	Override the class-level options, such as retry and backoff policies.

Definition at line 137 of file subscription_admin_client.h.