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

Definition at line 22 of file subscription_admin_client.cc.

◆ SubscriptionAdminClient() [2/2]

google::cloud::pubsub::v1::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::v1::SubscriptionAdminClient::CreateSnapshot ( Subscription const &  subscription,
Snapshot const &  snapshot,
SnapshotBuilder  builder = {} 
)
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";
}
Objects of this class identify a Cloud Pub/Sub snapshot.
Definition: snapshot.h:37
Performs subscription administrative operations in Cloud Pub/Sub.
StatusOr< google::pubsub::v1::Snapshot > CreateSnapshot(Subscription const &subscription, SnapshotBuilder builder={})
Creates a new snapshot for a subscription with a server-assigned name.
Objects of this class identify a Cloud Pub/Sub subscription.
Definition: subscription.h:37
Contains all the Cloud Pubsub C++ client types and functions.
Definition: ack_handler.cc:20
Parameters
subscriptionthe name of the subscription
snapshotthe name of the snapshot
builderadditional configuration for the snapshot, e.g., labels
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 220 of file subscription_admin_client.h.

◆ CreateSnapshot() [2/2]

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::v1::SubscriptionAdminClient::CreateSnapshot ( Subscription const &  subscription,
SnapshotBuilder  builder = {} 
)
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
subscriptionthe name of the subscription
builderadditional configuration for the snapshot, e.g., labels

Definition at line 197 of file subscription_admin_client.h.

◆ CreateSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::v1::SubscriptionAdminClient::CreateSubscription ( Topic const &  topic,
Subscription const &  subscription,
SubscriptionBuilder  builder = {} 
)
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";
}
StatusOr< google::pubsub::v1::Subscription > CreateSubscription(Topic const &topic, Subscription const &subscription, SubscriptionBuilder builder={})
Creates a new subscription in Cloud Pub/Sub.
Objects of this class identify a Cloud Pub/Sub topic.
Definition: topic.h:37
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)),
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";
}
Helper class to create google::pubsub::v1::PushConfig protos.
PushConfigBuilder & set_push_endpoint(std::string v) &
Create a Cloud Pub/Sub subscription configuration.
SubscriptionBuilder & set_push_config(PushConfigBuilder v) &
Parameters
topicthe topic that the subscription will attach to
subscriptionthe name for the subscription
builderany additional configuration for the subscription

Definition at line 91 of file subscription_admin_client.h.

◆ DeleteSnapshot()

Status google::cloud::pubsub::v1::SubscriptionAdminClient::DeleteSnapshot ( Snapshot const &  snapshot)
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
snapshotthe name of the snapshot
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 298 of file subscription_admin_client.h.

◆ DeleteSubscription()

Status google::cloud::pubsub::v1::SubscriptionAdminClient::DeleteSubscription ( Subscription  subscription)
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) {
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";
}
Status DeleteSubscription(Subscription subscription)
Deletes an existing subscription in Cloud Pub/Sub.
Parameters
subscriptionthe name of the subscription to be deleted.

Definition at line 158 of file subscription_admin_client.h.

◆ GetSnapshot()

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::v1::SubscriptionAdminClient::GetSnapshot ( Snapshot const &  snapshot)
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";
}
StatusOr< google::pubsub::v1::Snapshot > GetSnapshot(Snapshot const &snapshot)
Gets information about an existing snapshot.
Parameters
snapshotthe name of the snapshot
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 241 of file subscription_admin_client.h.

◆ GetSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::v1::SubscriptionAdminClient::GetSubscription ( Subscription  subscription)
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";
}
StatusOr< google::pubsub::v1::Subscription > GetSubscription(Subscription subscription)
Gets the metadata for an existing Cloud Pub/Sub subscription.

Definition at line 107 of file subscription_admin_client.h.

◆ ListSnapshots()

ListSnapshotsRange google::cloud::pubsub::v1::SubscriptionAdminClient::ListSnapshots ( std::string const &  project_id)
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";
}
}
ListSnapshotsRange ListSnapshots(std::string const &project_id)
Lists all the snapshots for a given project id.
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 279 of file subscription_admin_client.h.

◆ ListSubscriptions()

ListSubscriptionsRange google::cloud::pubsub::v1::SubscriptionAdminClient::ListSubscriptions ( std::string const &  project_id)
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";
}
}
ListSubscriptionsRange ListSubscriptions(std::string const &project_id)
Lists all the subscriptions for a given project id.

Definition at line 140 of file subscription_admin_client.h.

◆ ModifyPushSubscription()

Status google::cloud::pubsub::v1::SubscriptionAdminClient::ModifyPushSubscription ( Subscription const &  subscription,
PushConfigBuilder  builder 
)
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)),
if (!status.ok()) throw std::runtime_error(status.message());
std::cout << "The subscription push configuration was successfully"
<< " modified\n";
}
Status ModifyPushSubscription(Subscription const &subscription, PushConfigBuilder builder)
Modifies an existing subscription's push configuration.
Parameters
subscriptionthe name of the subscription to be modified.
buildera description of the changes to be made.

Definition at line 179 of file subscription_admin_client.h.

◆ Seek() [1/2]

StatusOr< google::pubsub::v1::SeekResponse > google::cloud::pubsub::v1::SubscriptionAdminClient::Seek ( Subscription const &  subscription,
Snapshot const &  snapshot 
)

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() -
if (!response.ok()) throw std::runtime_error(response.status().message());
std::cout << "The subscription seek was successful: "
<< response->DebugString() << "\n";
}
StatusOr< google::pubsub::v1::SeekResponse > Seek(Subscription const &subscription, std::chrono::system_clock::time_point timestamp)
Seeks a subscription to its state at timestamp.
std::chrono::seconds seconds
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's Seek() functionality.

Definition at line 36 of file subscription_admin_client.cc.

◆ Seek() [2/2]

StatusOr< google::pubsub::v1::SeekResponse > google::cloud::pubsub::v1::SubscriptionAdminClient::Seek ( Subscription const &  subscription,
std::chrono::system_clock::time_point  timestamp 
)

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() -
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.

Definition at line 26 of file subscription_admin_client.cc.

◆ UpdateSnapshot()

StatusOr<google::pubsub::v1::Snapshot> google::cloud::pubsub::v1::SubscriptionAdminClient::UpdateSnapshot ( Snapshot const &  snapshot,
SnapshotBuilder  builder 
)
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";
}
Build a request to create a Cloud Pub/Sub snapshot.
SnapshotBuilder & add_label(std::string const &key, std::string const &value) &
StatusOr< google::pubsub::v1::Snapshot > UpdateSnapshot(Snapshot const &snapshot, SnapshotBuilder builder)
Updates an existing snapshot.
Parameters
snapshotthe name of the snapshot
builderthe changes applied to the snapshot
See also
https://cloud.google.com/pubsub/docs/replay-overview for a detailed description of Cloud Pub/Sub's snapshots.

Definition at line 261 of file subscription_admin_client.h.

◆ UpdateSubscription()

StatusOr<google::pubsub::v1::Subscription> google::cloud::pubsub::v1::SubscriptionAdminClient::UpdateSubscription ( Subscription const &  subscription,
SubscriptionBuilder  builder 
)
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)),
if (!s) throw std::runtime_error(s.status().message());
std::cout << "The subscription has been updated to: " << s->DebugString()
<< "\n";
}
StatusOr< google::pubsub::v1::Subscription > UpdateSubscription(Subscription const &subscription, SubscriptionBuilder builder)
Updates an existing subscription in Cloud Pub/Sub.
SubscriptionBuilder & set_ack_deadline(std::chrono::seconds v) &
Parameters
subscriptionthe name for the subscription
builderany additional configuration for the subscription

Definition at line 125 of file subscription_admin_client.h.