Class TopicAdminClient (2.17.0)

Performs topic admin operations in Cloud Pub/Sub.

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

Performance

TopicAdminClient objects are cheap to create, copy, and move. However, each TopicAdminClient object must be created with a std::shared_ptr<TopicAdminConnection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeTopicAdminConnection() function and the TopicAdminConnection 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

TopicAdminClient(std::shared_ptr< TopicAdminConnection >, Options)

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

TopicAdminClient()

The default constructor is deleted.

Use PublisherClient(std::shared_ptr<PublisherConnection>)

Functions

CreateTopic(TopicBuilder, Options)

Creates a new topic in Cloud Pub/Sub.

Idempotency

This operation is idempotent, as it succeeds only once, therefore the library retries the call. It might return a status code of kAlreadyExists as a consequence of retrying a successful (but reported as failed) request.

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](pubsub::TopicAdminClient client, std::string project_id,
     std::string topic_id) {
    auto topic = client.CreateTopic(pubsub::TopicBuilder(
        pubsub::Topic(std::move(project_id), std::move(topic_id))));
    // Note that kAlreadyExists is a possible error when the library retries.
    if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The topic already exists\n";
      return;
    }
    if (!topic) throw std::move(topic).status();

    std::cout << "The topic was successfully created: " << topic->DebugString()
              << "\n";
  }
Parameters
Name Description
builder TopicBuilder

the configuration for the new topic, includes the name.

opts Options

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

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

CreateTopic(google::pubsub::v1::Topic, Options)

Create a new topic in Cloud Pub/Sub.

Parameters
Name Description
request google::pubsub::v1::Topic
opts Options
Returns
Type Description
StatusOr< google::pubsub::v1::Topic >

GetTopic(Topic, Options)

Gets information about an existing Cloud Pub/Sub topic.

Idempotency

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

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](pubsub::TopicAdminClient client, std::string project_id,
     std::string topic_id) {
    auto topic = client.GetTopic(
        pubsub::Topic(std::move(project_id), std::move(topic_id)));
    if (!topic) throw std::move(topic).status();

    std::cout << "The topic information was successfully retrieved: "
              << topic->DebugString() << "\n";
  }
Parameters
Name Description
topic Topic
opts Options
Returns
Type Description
StatusOr< google::pubsub::v1::Topic >

UpdateTopic(TopicBuilder, Options)

Updates the configuration of an existing Cloud Pub/Sub topic.

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::TopicAdminClient client, std::string project_id,
     std::string topic_id) {
    auto topic = client.UpdateTopic(
        pubsub::TopicBuilder(
            pubsub::Topic(std::move(project_id), std::move(topic_id)))
            .add_label("test-key", "test-value"));
    if (!topic) throw std::move(topic).status();

    std::cout << "The topic was successfully updated: " << topic->DebugString()
              << "\n";
  }
Parameters
Name Description
builder TopicBuilder

the configuration for the new topic, includes the name.

opts Options

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

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

ListTopics(std::string const &, Options)

Lists all the topics 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::TopicAdminClient client, std::string const& project_id) {
    int count = 0;
    for (auto& topic : client.ListTopics(project_id)) {
      if (!topic) throw std::move(topic).status();
      std::cout << "Topic Name: " << topic->name() << "\n";
      ++count;
    }
    if (count == 0) {
      std::cout << "No topics found in project " << project_id << "\n";
    }
  }
Parameters
Name Description
project_id std::string const &
opts Options
Returns
Type Description
ListTopicsRange

DeleteTopic(Topic, Options)

Deletes an existing topic 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::TopicAdminClient client, std::string const& project_id,
     std::string const& topic_id) {
    auto status = client.DeleteTopic(pubsub::Topic(project_id, topic_id));
    // Note that kNotFound is a possible result when the library retries.
    if (status.code() == google::cloud::StatusCode::kNotFound) {
      std::cout << "The topic was not found\n";
      return;
    }
    if (!status.ok()) throw std::runtime_error(status.message());

    std::cout << "The topic was successfully deleted\n";
  }
Parameters
Name Description
topic Topic

the name of the topic to be deleted.

opts Options

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

Returns
Type Description
Status

DetachSubscription(Subscription, Options)

Detaches an existing subscription.

This operation stops the subscription from receiving any further messages, it drops any messages still retained by the subscription, and any outstanding pull requests will fail with kFailedPrecondition.

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::TopicAdminClient client, std::string const& project_id,
     std::string const& subscription_id) {
    auto response = client.DetachSubscription(
        pubsub::Subscription(project_id, subscription_id));
    if (!response.ok()) throw std::move(response).status();

    std::cout << "The subscription was successfully detached: "
              << response->DebugString() << "\n";
  }
Parameters
Name Description
subscription Subscription

the name of the subscription to detach.

opts Options

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

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

ListTopicSubscriptions(Topic const &, Options)

Lists all the subscription names for a given topic.

Idempotency

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

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](pubsub::TopicAdminClient client, std::string const& project_id,
     std::string const& topic_id) {
    auto const topic = pubsub::Topic(project_id, topic_id);
    std::cout << "Subscription list for topic " << topic << ":\n";
    for (auto& name : client.ListTopicSubscriptions(topic)) {
      if (!name) throw std::move(name).status();
      std::cout << "  " << *name << "\n";
    }
  }
Parameters
Name Description
topic Topic const &
opts Options
Returns
Type Description
ListTopicSubscriptionsRange

ListTopicSnapshots(Topic const &, Options)

Lists all the subscription names for a given topic.

Idempotency

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

Example
  namespace pubsub = ::google::cloud::pubsub;
  [](pubsub::TopicAdminClient client, std::string project_id,
     std::string topic_id) {
    auto const topic =
        pubsub::Topic(std::move(project_id), std::move(topic_id));
    std::cout << "Snapshot list for topic " << topic << ":\n";
    for (auto& name : client.ListTopicSnapshots(topic)) {
      if (!name) throw std::move(name).status();
      std::cout << "  " << *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
topic Topic const &
opts Options
Returns
Type Description
ListTopicSnapshotsRange