Class SubscriptionAdminClient (2.19.0)

Version 2.19.0

• 2.31.0-rc (latest)
• 2.30.0
• 2.29.0
• 2.28.0
• 2.27.0
• 2.26.0
• 2.25.1
• 2.24.0
• 2.23.0
• 2.22.0
• 2.21.0
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.0
• 2.16.0
• 2.15.1
• 2.14.0
• 2.13.0
• 2.12.0
• 2.11.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, topic_id),
        pubsub::Subscription(project_id, 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, topic_id),
        pubsub::Subscription(project_id, 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, topic_id),
        pubsub::Subscription(project_id, subscription_id),
        pubsub::SubscriptionBuilder{}.set_bigquery_config(
            pubsub::BigQueryConfigBuilder{}.set_table(table_id)));
    if (!sub) {
      if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
        std::cout << "The subscription already exists\n";
        return;
      }
      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, 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, 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(project_id, 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, 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, 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(project_id, 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, 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 >