Class SubscriptionAdminClient (2.21.0-rc)

A service to manipulate subscriptions.

Equality

Instances of this class created via copy-construction or copy-assignment always compare equal. Instances created with equal std::shared_ptr<*Connection> objects compare equal. Objects that compare equal share the same underlying resources.

Performance

Creating a new instance of this class is a relatively expensive operation, new objects establish new connections to the service. In contrast, copy-construction, move-construction, and the corresponding assignment operations are relatively efficient as the copies share all underlying resources.

Thread Safety

Concurrent access to different instances of this class, even if they compare equal, is guaranteed to work. Two or more threads operating on the same instance of this class is not guaranteed to work. Since copy-construction and move-construction is a relatively efficient operation, consider using such a copy when using this class from multiple threads.

Constructors

SubscriptionAdminClient(SubscriptionAdminClient const &)

Copy and move support

Parameter
NameDescription
SubscriptionAdminClient const &

SubscriptionAdminClient(SubscriptionAdminClient &&)

Copy and move support

Parameter
NameDescription
SubscriptionAdminClient &&

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

Parameters
NameDescription
connection std::shared_ptr< SubscriptionAdminConnection >
opts Options

Operators

operator=(SubscriptionAdminClient const &)

Copy and move support

Parameter
NameDescription
SubscriptionAdminClient const &
Returns
TypeDescription
SubscriptionAdminClient &

operator=(SubscriptionAdminClient &&)

Copy and move support

Parameter
NameDescription
SubscriptionAdminClient &&
Returns
TypeDescription
SubscriptionAdminClient &

Functions

CreateSubscription(std::string const &, std::string const &, google::pubsub::v1::PushConfig const &, std::int32_t, Options)

Creates a subscription to a given topic.

See the resource name rules. If the subscription already exists, returns ALREADY_EXISTS. If the corresponding topic doesn't exist, returns NOT_FOUND.

If the name is not provided in the request, the server will assign a random name for this subscription on the same project as the topic, conforming to the resource name format. The generated name is populated in the returned Subscription object. Note that for REST API requests, you must specify a name in the request.

Parameters
NameDescription
name std::string const &

Required. The name of the subscription. It must have the format "projects/{project}/subscriptions/{subscription}". {subscription} must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and it must not start with "goog".

topic std::string const &

Required. The name of the topic from which this subscription is receiving messages. Format is projects/{project}/topics/{topic}. The value of this field will be _deleted-topic_ if the topic has been deleted.

push_config google::pubsub::v1::PushConfig const &

Optional. If push delivery is used with this subscription, this field is used to configure it.

ack_deadline_seconds std::int32_t

Optional. The approximate amount of time (on a best-effort basis) Pub/Sub waits for the subscriber to acknowledge receipt before resending the message. In the interval after the message is delivered and before it is acknowledged, it is considered to be outstanding. During that time period, the message will not be redelivered (on a best-effort basis).
For pull subscriptions, this value is used as the initial value for the ack deadline. To override this value for a given message, call ModifyAckDeadline with the corresponding ack_id if using non-streaming pull or send the ack_id in a StreamingModifyAckDeadlineRequest if using streaming pull. The minimum custom deadline you can specify is 10 seconds. The maximum custom deadline you can specify is 600 seconds (10 minutes). If this parameter is 0, a default value of 10 seconds is used.
For push delivery, this value is also used to set the request timeout for the call to the push endpoint.
If the subscriber never acknowledges the message, the Pub/Sub system will eventually redeliver the message.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

CreateSubscription(google::pubsub::v1::Subscription const &, Options)

Creates a subscription to a given topic.

See the resource name rules. If the subscription already exists, returns ALREADY_EXISTS. If the corresponding topic doesn't exist, returns NOT_FOUND.

If the name is not provided in the request, the server will assign a random name for this subscription on the same project as the topic, conforming to the resource name format. The generated name is populated in the returned Subscription object. Note that for REST API requests, you must specify a name in the request.

Parameters
NameDescription
request google::pubsub::v1::Subscription const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.Subscription. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetSubscription(std::string const &, Options)

Gets the configuration details of a subscription.

Parameters
NameDescription
subscription std::string const &

Required. The name of the subscription to get. Format is projects/{project}/subscriptions/{sub}.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetSubscription(google::pubsub::v1::GetSubscriptionRequest const &, Options)

Gets the configuration details of a subscription.

Parameters
NameDescription
request google::pubsub::v1::GetSubscriptionRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.GetSubscriptionRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateSubscription(google::pubsub::v1::Subscription const &, google::protobuf::FieldMask const &, Options)

Updates an existing subscription by updating the fields specified in the update mask.

Note that certain properties of a subscription, such as its topic, are not modifiable.

Parameters
NameDescription
subscription google::pubsub::v1::Subscription const &

Required. The updated subscription object.

update_mask google::protobuf::FieldMask const &

Required. Indicates which fields in the provided subscription to update. Must be specified and non-empty.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateSubscription(google::pubsub::v1::UpdateSubscriptionRequest const &, Options)

Updates an existing subscription by updating the fields specified in the update mask.

Note that certain properties of a subscription, such as its topic, are not modifiable.

Parameters
NameDescription
request google::pubsub::v1::UpdateSubscriptionRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.UpdateSubscriptionRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Subscription >

the result of the RPC. The response message type (google.pubsub.v1.Subscription) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

ListSubscriptions(std::string const &, Options)

Lists matching subscriptions.

Parameters
NameDescription
project std::string const &

Required. The name of the project in which to list subscriptions. Format is projects/{project-id}.

opts Options

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

Returns
TypeDescription
StreamRange< google::pubsub::v1::Subscription >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.pubsub.v1.Subscription, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

ListSubscriptions(google::pubsub::v1::ListSubscriptionsRequest, Options)

Lists matching subscriptions.

Parameters
NameDescription
request google::pubsub::v1::ListSubscriptionsRequest

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.ListSubscriptionsRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StreamRange< google::pubsub::v1::Subscription >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.pubsub.v1.Subscription, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

DeleteSubscription(std::string const &, Options)

Deletes an existing subscription.

All messages retained in the subscription are immediately dropped. Calls to Pull after deletion will return NOT_FOUND. After a subscription is deleted, a new one may be created with the same name, but the new one has no association with the old subscription or its topic unless the same topic is specified.

Parameters
NameDescription
subscription std::string const &

Required. The subscription to delete. Format is projects/{project}/subscriptions/{sub}.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

DeleteSubscription(google::pubsub::v1::DeleteSubscriptionRequest const &, Options)

Deletes an existing subscription.

All messages retained in the subscription are immediately dropped. Calls to Pull after deletion will return NOT_FOUND. After a subscription is deleted, a new one may be created with the same name, but the new one has no association with the old subscription or its topic unless the same topic is specified.

Parameters
NameDescription
request google::pubsub::v1::DeleteSubscriptionRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.DeleteSubscriptionRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

ModifyPushConfig(std::string const &, google::pubsub::v1::PushConfig const &, Options)

Modifies the PushConfig for a specified subscription.

This may be used to change a push subscription to a pull one (signified by an empty PushConfig) or vice versa, or change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery continuously through the call regardless of changes to the PushConfig.

Parameters
NameDescription
subscription std::string const &

Required. The name of the subscription. Format is projects/{project}/subscriptions/{sub}.

push_config google::pubsub::v1::PushConfig const &

Required. The push configuration for future deliveries.
An empty pushConfig indicates that the Pub/Sub system should stop pushing messages from the given subscription and allow messages to be pulled and acknowledged - effectively pausing the subscription if Pull or StreamingPull is not called.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

ModifyPushConfig(google::pubsub::v1::ModifyPushConfigRequest const &, Options)

Modifies the PushConfig for a specified subscription.

This may be used to change a push subscription to a pull one (signified by an empty PushConfig) or vice versa, or change the endpoint URL and other attributes of a push subscription. Messages will accumulate for delivery continuously through the call regardless of changes to the PushConfig.

Parameters
NameDescription
request google::pubsub::v1::ModifyPushConfigRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.ModifyPushConfigRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

GetSnapshot(std::string const &, Options)

Gets the configuration details of a snapshot.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
snapshot std::string const &

Required. The name of the snapshot to get. Format is projects/{project}/snapshots/{snap}.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

GetSnapshot(google::pubsub::v1::GetSnapshotRequest const &, Options)

Gets the configuration details of a snapshot.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
request google::pubsub::v1::GetSnapshotRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.GetSnapshotRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

ListSnapshots(std::string const &, Options)

Lists the existing snapshots.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
project std::string const &

Required. The name of the project in which to list snapshots. Format is projects/{project-id}.

opts Options

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

Returns
TypeDescription
StreamRange< google::pubsub::v1::Snapshot >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.pubsub.v1.Snapshot, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

ListSnapshots(google::pubsub::v1::ListSnapshotsRequest, Options)

Lists the existing snapshots.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
request google::pubsub::v1::ListSnapshotsRequest

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.ListSnapshotsRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StreamRange< google::pubsub::v1::Snapshot >

a StreamRange to iterate of the results. See the documentation of this type for details. In brief, this class has begin() and end() member functions returning a iterator class meeting the input iterator requirements. The value type for this iterator is a StatusOr as the iteration may fail even after some values are retrieved successfully, for example, if there is a network disconnect. An empty set of results does not indicate an error, it indicates that there are no resources meeting the request criteria. On a successful iteration the StatusOr<T> contains elements of type google.pubsub.v1.Snapshot, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

CreateSnapshot(std::string const &, std::string const &, Options)

Creates a snapshot from the requested subscription.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. If the snapshot already exists, returns ALREADY_EXISTS. If the requested subscription doesn't exist, returns NOT_FOUND. If the backlog in the subscription is too old – and the resulting snapshot would expire in less than 1 hour – then FAILED_PRECONDITION is returned. See also the Snapshot.expire_time field. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription, conforming to the resource name format. The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

Parameters
NameDescription
name std::string const &

Required. User-provided name for this snapshot. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription. Note that for REST API requests, you must specify a name. See the resource name rules. Format is projects/{project}/snapshots/{snap}.

subscription std::string const &

Required. The subscription whose backlog the snapshot retains. Specifically, the created snapshot is guaranteed to retain: (a) The existing backlog on the subscription. More precisely, this is defined as the messages in the subscription's backlog that are unacknowledged upon the successful completion of the CreateSnapshot request; as well as: (b) Any messages published to the subscription's topic following the successful completion of the CreateSnapshot request. Format is projects/{project}/subscriptions/{sub}.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

CreateSnapshot(google::pubsub::v1::CreateSnapshotRequest const &, Options)

Creates a snapshot from the requested subscription.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. If the snapshot already exists, returns ALREADY_EXISTS. If the requested subscription doesn't exist, returns NOT_FOUND. If the backlog in the subscription is too old – and the resulting snapshot would expire in less than 1 hour – then FAILED_PRECONDITION is returned. See also the Snapshot.expire_time field. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription, conforming to the resource name format. The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

Parameters
NameDescription
request google::pubsub::v1::CreateSnapshotRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.CreateSnapshotRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateSnapshot(google::pubsub::v1::Snapshot const &, google::protobuf::FieldMask const &, Options)

Updates an existing snapshot by updating the fields specified in the update mask.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
snapshot google::pubsub::v1::Snapshot const &

Required. The updated snapshot object.

update_mask google::protobuf::FieldMask const &

Required. Indicates which fields in the provided snapshot to update. Must be specified and non-empty.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

UpdateSnapshot(google::pubsub::v1::UpdateSnapshotRequest const &, Options)

Updates an existing snapshot by updating the fields specified in the update mask.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot.

Parameters
NameDescription
request google::pubsub::v1::UpdateSnapshotRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.UpdateSnapshotRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
StatusOr< google::pubsub::v1::Snapshot >

the result of the RPC. The response message type (google.pubsub.v1.Snapshot) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the StatusOr contains the error details.

DeleteSnapshot(std::string const &, Options)

Removes an existing snapshot.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. When the snapshot is deleted, all messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified.

Parameters
NameDescription
snapshot std::string const &

Required. The name of the snapshot to delete. Format is projects/{project}/snapshots/{snap}.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

DeleteSnapshot(google::pubsub::v1::DeleteSnapshotRequest const &, Options)

Removes an existing snapshot.

Snapshots are used in Seek operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. When the snapshot is deleted, all messages retained in the snapshot are immediately dropped. After a snapshot is deleted, a new one may be created with the same name, but the new one has no association with the old snapshot or its subscription, unless the same subscription is specified.

Parameters
NameDescription
request google::pubsub::v1::DeleteSnapshotRequest const &

Unary RPCs, such as the one wrapped by this function, receive a single request proto message which includes all the inputs for the RPC. In this case, the proto message is a google.pubsub.v1.DeleteSnapshotRequest. Proto messages are converted to C++ classes by Protobuf, using the Protobuf mapping rules.

opts Options

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

Returns
TypeDescription
Status

a Status object. If the request failed, the status contains the details of the failure.

<