Class SubscriptionAdminClient (2.23.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.

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 >

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.

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
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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

Type Description

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.

Parameters
Name	Description
`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

Type Description

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
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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.

Parameters
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`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
Name	Description
`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
Type	Description
`Status`	a `Status` object. If the request failed, the status contains the details of the failure.

Seek(google::pubsub::v1::SeekRequest const &, Options)

Seeks an existing subscription to a point in time or to a given snapshot, whichever is provided in the request.

Parameters
Name	Description
`request`	`google::pubsub::v1::SeekRequest 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.SeekRequest. 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::SeekResponse >`	the result of the RPC. The response message type (google.pubsub.v1.SeekResponse) is mapped to a C++ class using the Protobuf mapping rules. If the request fails, the `StatusOr` contains the error details.