Class SubscriptionAdminClient (2.32.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
Name Description
SubscriptionAdminClient const &

SubscriptionAdminClient(SubscriptionAdminClient &&)

Copy and move support

Parameter
Name Description
SubscriptionAdminClient &&

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

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

Operators

operator=(SubscriptionAdminClient const &)

Copy and move support

Parameter
Name Description
SubscriptionAdminClient const &
Returns
Type Description
SubscriptionAdminClient &

operator=(SubscriptionAdminClient &&)

Copy and move support

Parameter
Name Description
SubscriptionAdminClient &&
Returns
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description
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
Type Description
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
Name Description