Performs topic admin operations in Cloud Pub/Sub.
More...
#include <google/cloud/pubsub/topic_admin_client.h>
|
| TopicAdminClient (std::shared_ptr< TopicAdminConnection > connection, Options opts={}) |
|
| TopicAdminClient ()=delete |
| The default constructor is deleted. More...
|
|
StatusOr< google::pubsub::v1::Topic > | CreateTopic (TopicBuilder builder, Options opts={}) |
| Creates a new topic in Cloud Pub/Sub. More...
|
|
StatusOr< google::pubsub::v1::Topic > | CreateTopic (google::pubsub::v1::Topic request, Options opts={}) |
| Create a new topic in Cloud Pub/Sub. More...
|
|
StatusOr< google::pubsub::v1::Topic > | GetTopic (Topic topic, Options opts={}) |
| Gets information about an existing Cloud Pub/Sub topic. More...
|
|
StatusOr< google::pubsub::v1::Topic > | UpdateTopic (TopicBuilder builder, Options opts={}) |
| Updates the configuration of an existing Cloud Pub/Sub topic. More...
|
|
ListTopicsRange | ListTopics (std::string const &project_id, Options opts={}) |
| Lists all the topics for a given project id. More...
|
|
Status | DeleteTopic (Topic topic, Options opts={}) |
| Deletes an existing topic in Cloud Pub/Sub. More...
|
|
StatusOr< google::pubsub::v1::DetachSubscriptionResponse > | DetachSubscription (Subscription subscription, Options opts={}) |
| Detaches an existing subscription. More...
|
|
ListTopicSubscriptionsRange | ListTopicSubscriptions (Topic const &topic, Options opts={}) |
| Lists all the subscription names for a given topic. More...
|
|
ListTopicSnapshotsRange | ListTopicSnapshots (Topic const &topic, Options opts={}) |
| Lists all the subscription names for a given topic. More...
|
|
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.
Definition at line 59 of file topic_admin_client.h.
◆ TopicAdminClient() [1/2]
◆ TopicAdminClient() [2/2]
google::cloud::pubsub::TopicAdminClient::TopicAdminClient |
( |
| ) |
|
|
delete |
◆ CreateTopic() [1/2]
StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::TopicAdminClient::CreateTopic |
( |
google::pubsub::v1::Topic |
request, |
|
|
Options |
opts = {} |
|
) |
| |
|
inline |
◆ CreateTopic() [2/2]
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))));
std::cout << "The topic already exists\n";
return;
}
if (!topic) throw std::runtime_error(topic.status().message());
std::cout << "The topic was successfully created: " << topic->DebugString()
<< "\n";
}
- Parameters
-
builder | the configuration for the new topic, includes the name. |
opts | Override the class-level options, such as retry and backoff policies. |
Definition at line 87 of file topic_admin_client.h.
◆ DeleteTopic()
Status google::cloud::pubsub::TopicAdminClient::DeleteTopic |
( |
Topic |
topic, |
|
|
Options |
opts = {} |
|
) |
| |
|
inline |
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(std::move(project_id), std::move(topic_id)));
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
-
topic | the name of the topic to be deleted. |
opts | Override the class-level options, such as retry and backoff policies. |
Definition at line 168 of file topic_admin_client.h.
◆ DetachSubscription()
StatusOr<google::pubsub::v1::DetachSubscriptionResponse> google::cloud::pubsub::TopicAdminClient::DetachSubscription |
( |
Subscription |
subscription, |
|
|
Options |
opts = {} |
|
) |
| |
|
inline |
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 project_id,
std::string subscription_id) {
auto response = client.DetachSubscription(pubsub::Subscription(
std::move(project_id), std::move(subscription_id)));
if (!response.ok()) return;
std::cout << "The subscription was successfully detached: "
<< response->DebugString() << "\n";
}
- Parameters
-
subscription | the name of the subscription to detach. |
opts | Override the class-level options, such as retry and backoff policies. |
Definition at line 192 of file topic_admin_client.h.
◆ GetTopic()
StatusOr<google::pubsub::v1::Topic> google::cloud::pubsub::TopicAdminClient::GetTopic |
( |
Topic |
topic, |
|
|
Options |
opts = {} |
|
) |
| |
|
inline |
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::runtime_error(topic.status().message());
std::cout << "The topic information was successfully retrieved: "
<< topic->DebugString() << "\n";
}
Definition at line 110 of file topic_admin_client.h.
◆ ListTopics()
ListTopicsRange google::cloud::pubsub::TopicAdminClient::ListTopics |
( |
std::string const & |
project_id, |
|
|
Options |
opts = {} |
|
) |
| |
|
inline |
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 const& topic : client.ListTopics(project_id)) {
if (!topic) throw std::runtime_error(topic.status().message());
std::cout << "Topic Name: " << topic->name() << "\n";
++count;
}
if (count == 0) {
std::cout << "No topics found in project " << project_id << "\n";
}
}
Definition at line 146 of file topic_admin_client.h.
◆ ListTopicSnapshots()
Lists all the subscription names for a given topic.
- Note
- The returned range contains fully qualified snapshot names, e.g.,
"projects/my-project/snapshots/my-subscription"
. Applications may need to parse these names to use with other APIs.
- 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 const& name : client.ListTopicSnapshots(topic)) {
if (!name) throw std::runtime_error(name.status().message());
std::cout << " " << *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 237 of file topic_admin_client.h.
◆ ListTopicSubscriptions()
Lists all the subscription names for a given topic.
- Note
- The returned range contains fully qualified subscription names, e.g.,
"projects/my-project/subscriptions/my-subscription"
. Applications may need to parse these names to use with other APIs.
- 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 << "Subscription list for topic " << topic << ":\n";
for (auto const& name : client.ListTopicSubscriptions(topic)) {
if (!name) throw std::runtime_error(name.status().message());
std::cout << " " << *name << "\n";
}
}
Definition at line 213 of file topic_admin_client.h.
◆ UpdateTopic()
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) return;
std::cout << "The topic was successfully updated: " << topic->DebugString()
<< "\n";
}
- Parameters
-
builder | the configuration for the new topic, includes the name. |
opts | Override the class-level options, such as retry and backoff policies. |
Definition at line 130 of file topic_admin_client.h.