Class SubscriptionAdminClient (2.12.0)

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.

Constructors

SubscriptionAdminClient(std::shared_ptr< SubscriptionAdminConnection >, Options)

Parameters
Name Description
connection std::shared_ptr< SubscriptionAdminConnection >
opts Options

SubscriptionAdminClient()

The default constructor is deleted.

Use SubscriberClient(std::shared_ptr<SubscriberConnection>)

Functions

CreateSubscription(Topic const &, Subscription const &, SubscriptionBuilder, Options)

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::move(sub).status();

    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::move(sub).status();

    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::move(sub).status();

    std::cout << "The subscription was successfully created: "
              << sub->DebugString() << "\n";
  }
Parameters
Name Description
topic Topic const &

the topic that the subscription will attach to

subscription Subscription const &

the name for the subscription

builder SubscriptionBuilder

any additional configuration for the subscription

opts Options

Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::pubsub::v1::Subscription >

GetSubscription(Subscription, Options)

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::move(sub).status();

    std::cout << "The subscription exists and its metadata is: "
              << sub->DebugString() << "\n";
  }
Parameters
Name Description
subscription Subscription
opts Options
Returns
Type Description
StatusOr< google::pubsub::v1::Subscription >

UpdateSubscription(Subscription const &, SubscriptionBuilder, Options)

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::move(s).status();

    std::cout << "The subscription has been updated to: " << s->DebugString()
              << "\n";
  }
Parameters
Name Description
subscription Subscription const &

the name for the subscription

builder SubscriptionBuilder

any additional configuration for the subscription

opts Options

Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::pubsub::v1::Subscription >

ListSubscriptions(std::string const &, Options)

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& subscription : client.ListSubscriptions(project_id)) {
      if (!subscription) throw std::move(subscription).status();
      std::cout << "Subscription Name: " << subscription->name() << "\n";
      ++count;
    }
    if (count == 0) {
      std::cout << "No subscriptions found in project " << project_id << "\n";
    }
  }
Parameters
Name Description
project_id std::string const &
opts Options
Returns
Type Description
ListSubscriptionsRange

DeleteSubscription(Subscription, Options)

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
Name Description
subscription Subscription

the name of the subscription to be deleted.

opts Options

Override the class-level options, such as retry and backoff policies.

Returns
Type Description
Status

ModifyPushSubscription(Subscription const &, PushConfigBuilder, Options)

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
Name Description
subscription Subscription const &

the name of the subscription to be modified.

builder PushConfigBuilder

a description of the changes to be made.

opts Options

Override the class-level options, such as retry and backoff policies.

Returns
Type Description
Status

CreateSnapshot(Subscription const &, SnapshotBuilder, Options)

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
Name Description
subscription Subscription const &

the name of the subscription

builder SnapshotBuilder

additional configuration for the snapshot, e.g., labels

opts Options

Override the class-level options, such as retry and backoff policies.

Returns
Type Description
StatusOr< google::pubsub::v1::Snapshot >

CreateSnapshot(Subscription const &, Snapshot const &, SnapshotBuilder, Options)

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::move(snapshot).status();

    std::cout << "The snapshot was successfully created: "
              << snapshot->DebugString() << "\n";
  }
See Also

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

Parameters
Name Description
subscription Subscription const &

the name of the subscription

snapshot Snapshot const &

the name of the snapshot

builder SnapshotBuilder

additional configuration for the snapshot, e.g., labels

opts Options

Override the class-level options, such as retry and backoff policies.
Returns
Type Description
StatusOr< google::pubsub::v1::Snapshot >

GetSnapshot(Snapshot const &, Options)

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::move(response).status();

    std::cout << "The snapshot details are: " << response->DebugString()
              << "\n";
  }
See Also

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

Parameters
Name Description
snapshot Snapshot const &

the name of the snapshot

opts Options

Override the class-level options, such as retry and backoff policies.
Returns
Type Description
StatusOr< google::pubsub::v1::Snapshot >

UpdateSnapshot(Snapshot const &, SnapshotBuilder, Options)

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()) throw std::move(snap).status();

    std::cout << "The snapshot was successfully updated: "
              << snap->DebugString() << "\n";
  }
See Also

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

Parameters
Name Description
snapshot Snapshot const &

the name of the snapshot

builder SnapshotBuilder

the changes applied to the snapshot

opts Options

Override the class-level options, such as retry and backoff policies.
Returns
Type Description
StatusOr< google::pubsub::v1::Snapshot >

ListSnapshots(std::string const &, Options)

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& snapshot : client.ListSnapshots(project_id)) {
      if (!snapshot) throw std::move(snapshot).status();
      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.

Parameters
Name Description
project_id std::string const &
opts Options
Returns
Type Description
ListSnapshotsRange

DeleteSnapshot(Snapshot const &, Options)

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::move(snapshot).status();

    std::cout << "The snapshot was successfully created: "
              << snapshot->DebugString() << "\n";
  }
See Also

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

Parameters
Name Description
snapshot Snapshot const &

the name of the snapshot

opts Options

Override the class-level options, such as retry and backoff policies.
Returns
Type Description
Status

Seek(Subscription const &, std::chrono::system_clock::time_point, Options)

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::move(response).status();

    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.

Parameters
Name Description
subscription Subscription const &
timestamp std::chrono::system_clock::time_point
opts Options
Returns
Type Description
StatusOr< google::pubsub::v1::SeekResponse >

Seek(Subscription const &, Snapshot const &, Options)

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::move(response).status();

    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.

Parameters
Name Description
subscription Subscription const &
snapshot Snapshot const &
opts Options
Returns
Type Description
StatusOr< google::pubsub::v1::SeekResponse >