Class CloudTasksClient (3.12.0-rc)

Cloud Tasks allows developers to manage the execution of background work in their applications.

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

CloudTasksClient(CloudTasksClient const &)

Copy and move support

Parameter
Name Description
CloudTasksClient const &

CloudTasksClient(CloudTasksClient &&)

Copy and move support

Parameter
Name Description
CloudTasksClient &&

CloudTasksClient(std::shared_ptr< CloudTasksConnection >, Options)

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

Operators

operator=(CloudTasksClient const &)

Copy and move support

Parameter
Name Description
CloudTasksClient const &
Returns
Type Description
CloudTasksClient &

operator=(CloudTasksClient &&)

Copy and move support

Parameter
Name Description
CloudTasksClient &&
Returns
Type Description
CloudTasksClient &

Functions

ListQueues(std::string const &, Options)

Lists queues.

Queues are returned in lexicographical order.

Parameters
Name Description
parent std::string const &

Required. The location name. For example: projects/PROJECT_ID/locations/LOCATION_ID
opts Options

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

Returns
Type Description
StreamRange< google::cloud::tasks::v2::Queue >

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.cloud.tasks.v2.Queue, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

ListQueues(google::cloud::tasks::v2::ListQueuesRequest, Options)

Lists queues.

Queues are returned in lexicographical order.

Parameters
Name Description
request google::cloud::tasks::v2::ListQueuesRequest

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.cloud.tasks.v2.ListQueuesRequest. 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::cloud::tasks::v2::Queue >

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.cloud.tasks.v2.Queue, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

GetQueue(std::string const &, Options)

Gets a queue.

Parameters
Name Description
name std::string const &

Required. The resource name of the queue. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

GetQueue(google::cloud::tasks::v2::GetQueueRequest const &, Options)

Gets a queue.

Parameters
Name Description
request google::cloud::tasks::v2::GetQueueRequest 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.cloud.tasks.v2.GetQueueRequest. 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::cloud::tasks::v2::Queue >

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

CreateQueue(std::string const &, google::cloud::tasks::v2::Queue const &, Options)

Creates a queue.

Queues created with this method allow tasks to live for a maximum of 31 days. After a task is 31 days old, the task will be deleted regardless of whether it was dispatched or not.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
parent std::string const &

Required. The location name in which the queue will be created. For example: projects/PROJECT_ID/locations/LOCATION_ID
The list of allowed locations can be obtained by calling Cloud Tasks' implementation of ListLocations.

queue google::cloud::tasks::v2::Queue const &

Required. The queue to create.
Queue's name cannot be the same as an existing queue.

opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

CreateQueue(google::cloud::tasks::v2::CreateQueueRequest const &, Options)

Creates a queue.

Queues created with this method allow tasks to live for a maximum of 31 days. After a task is 31 days old, the task will be deleted regardless of whether it was dispatched or not.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
request google::cloud::tasks::v2::CreateQueueRequest 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.cloud.tasks.v2.CreateQueueRequest. 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::cloud::tasks::v2::Queue >

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

UpdateQueue(google::cloud::tasks::v2::Queue const &, google::protobuf::FieldMask const &, Options)

Updates a queue.

This method creates the queue if it does not exist and updates the queue if it does exist.

Queues created with this method allow tasks to live for a maximum of 31 days. After a task is 31 days old, the task will be deleted regardless of whether it was dispatched or not.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
queue google::cloud::tasks::v2::Queue const &

Required. The queue to create or update.
The queue's name must be specified.
Output only fields cannot be modified using UpdateQueue. Any value specified for an output only field will be ignored. The queue's name cannot be changed.

update_mask google::protobuf::FieldMask const &

A mask used to specify which fields of the queue are being updated.
If empty, then all fields will be updated.

opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

UpdateQueue(google::cloud::tasks::v2::UpdateQueueRequest const &, Options)

Updates a queue.

This method creates the queue if it does not exist and updates the queue if it does exist.

Queues created with this method allow tasks to live for a maximum of 31 days. After a task is 31 days old, the task will be deleted regardless of whether it was dispatched or not.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
request google::cloud::tasks::v2::UpdateQueueRequest 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.cloud.tasks.v2.UpdateQueueRequest. 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::cloud::tasks::v2::Queue >

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

DeleteQueue(std::string const &, Options)

Deletes a queue.

This command will delete the queue even if it has tasks in it.

Note: If you delete a queue, you may be prevented from creating a new queue with the same name as the deleted queue for a tombstone window of up to 3 days. During this window, the CreateQueue operation may appear to recreate the queue, but this can be misleading. If you attempt to create a queue with the same name as one that is in the tombstone window, run GetQueue to confirm that the queue creation was successful. If GetQueue returns 200 response code, your queue was successfully created with the name of the previously deleted queue. Otherwise, your queue did not successfully recreate.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
name std::string const &

Required. The queue name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
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.

DeleteQueue(google::cloud::tasks::v2::DeleteQueueRequest const &, Options)

Deletes a queue.

This command will delete the queue even if it has tasks in it.

Note: If you delete a queue, you may be prevented from creating a new queue with the same name as the deleted queue for a tombstone window of up to 3 days. During this window, the CreateQueue operation may appear to recreate the queue, but this can be misleading. If you attempt to create a queue with the same name as one that is in the tombstone window, run GetQueue to confirm that the queue creation was successful. If GetQueue returns 200 response code, your queue was successfully created with the name of the previously deleted queue. Otherwise, your queue did not successfully recreate.

WARNING: Using this method may have unintended side effects if you are using an App Engine queue.yaml or queue.xml file to manage your queues. Read Overview of Queue Management and queue.yaml before using this method.

Parameters
Name Description
request google::cloud::tasks::v2::DeleteQueueRequest 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.cloud.tasks.v2.DeleteQueueRequest. 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.

PurgeQueue(std::string const &, Options)

Purges a queue by deleting all of its tasks.

All tasks created before this method is called are permanently deleted.

Purge operations can take up to one minute to take effect. Tasks might be dispatched before the purge takes effect. A purge is irreversible.

Parameters
Name Description
name std::string const &

Required. The queue name. For example: projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

PurgeQueue(google::cloud::tasks::v2::PurgeQueueRequest const &, Options)

Purges a queue by deleting all of its tasks.

All tasks created before this method is called are permanently deleted.

Purge operations can take up to one minute to take effect. Tasks might be dispatched before the purge takes effect. A purge is irreversible.

Parameters
Name Description
request google::cloud::tasks::v2::PurgeQueueRequest 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.cloud.tasks.v2.PurgeQueueRequest. 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::cloud::tasks::v2::Queue >

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

PauseQueue(std::string const &, Options)

Pauses the queue.

If a queue is paused then the system will stop dispatching tasks until the queue is resumed via ResumeQueue. Tasks can still be added when the queue is paused. A queue is paused if its state is PAUSED.

Parameters
Name Description
name std::string const &

Required. The queue name. For example: projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

PauseQueue(google::cloud::tasks::v2::PauseQueueRequest const &, Options)

Pauses the queue.

If a queue is paused then the system will stop dispatching tasks until the queue is resumed via ResumeQueue. Tasks can still be added when the queue is paused. A queue is paused if its state is PAUSED.

Parameters
Name Description
request google::cloud::tasks::v2::PauseQueueRequest 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.cloud.tasks.v2.PauseQueueRequest. 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::cloud::tasks::v2::Queue >

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

ResumeQueue(std::string const &, Options)

Resume a queue.

This method resumes a queue after it has been PAUSED or DISABLED. The state of a queue is stored in the queue's state; after calling this method it will be set to RUNNING.

WARNING: Resuming many high-QPS queues at the same time can lead to target overloading. If you are resuming high-QPS queues, follow the 500/50/5 pattern described in Managing Cloud Tasks Scaling Risks.

Parameters
Name Description
name std::string const &

Required. The queue name. For example: projects/PROJECT_ID/location/LOCATION_ID/queues/QUEUE_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Queue >

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

ResumeQueue(google::cloud::tasks::v2::ResumeQueueRequest const &, Options)

Resume a queue.

This method resumes a queue after it has been PAUSED or DISABLED. The state of a queue is stored in the queue's state; after calling this method it will be set to RUNNING.

WARNING: Resuming many high-QPS queues at the same time can lead to target overloading. If you are resuming high-QPS queues, follow the 500/50/5 pattern described in Managing Cloud Tasks Scaling Risks.

Parameters
Name Description
request google::cloud::tasks::v2::ResumeQueueRequest 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.cloud.tasks.v2.ResumeQueueRequest. 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::cloud::tasks::v2::Queue >

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

GetIamPolicy(std::string const &, Options)

Gets the access control policy for a Queue.

Returns an empty policy if the resource exists and does not have a policy set.

Authorization requires the following Google IAM permission on the specified resource parent:

  • cloudtasks.queues.getIamPolicy
Parameters
Name Description
resource std::string const &

REQUIRED: The resource for which the policy is being requested. See the operation documentation for the appropriate value for this field.

opts Options

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

Returns
Type Description
StatusOr< google::iam::v1::Policy >

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

GetIamPolicy(google::iam::v1::GetIamPolicyRequest const &, Options)

Gets the access control policy for a Queue.

Returns an empty policy if the resource exists and does not have a policy set.

Authorization requires the following Google IAM permission on the specified resource parent:

  • cloudtasks.queues.getIamPolicy
Parameters
Name Description
request google::iam::v1::GetIamPolicyRequest 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.iam.v1.GetIamPolicyRequest. 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::iam::v1::Policy >

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

SetIamPolicy(std::string const &, google::iam::v1::Policy const &, Options)

Sets the access control policy for a Queue.

Replaces any existing policy.

Note: The Cloud Console does not check queue-level IAM permissions yet. Project-level permissions are required to use the Cloud Console.

Authorization requires the following Google IAM permission on the specified resource parent:

  • cloudtasks.queues.setIamPolicy
Parameters
Name Description
resource std::string const &

REQUIRED: The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.

policy google::iam::v1::Policy const &

REQUIRED: The complete policy to be applied to the resource. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them.

opts Options

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

Returns
Type Description
StatusOr< google::iam::v1::Policy >

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

SetIamPolicy(std::string const &, IamUpdater const &, Options)

Updates the IAM policy for resource using an optimistic concurrency control loop.

The loop fetches the current policy for resource, and passes it to updater, which should return the new policy. This new policy should use the current etag so that the read-modify-write cycle can detect races and rerun the update when there is a mismatch. If the new policy does not have an etag, the existing policy will be blindly overwritten. If updater does not yield a policy, the control loop is terminated and kCancelled is returned.

Parameters
Name Description
resource std::string const &

Required. The resource for which the policy is being specified. See the operation documentation for the appropriate value for this field.

updater IamUpdater const &

Required. Functor to map the current policy to a new one.

opts Options

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

Returns
Type Description
StatusOr< google::iam::v1::Policy >

google::iam::v1::Policy

SetIamPolicy(google::iam::v1::SetIamPolicyRequest const &, Options)

Sets the access control policy for a Queue.

Replaces any existing policy.

Note: The Cloud Console does not check queue-level IAM permissions yet. Project-level permissions are required to use the Cloud Console.

Authorization requires the following Google IAM permission on the specified resource parent:

  • cloudtasks.queues.setIamPolicy
Parameters
Name Description
request google::iam::v1::SetIamPolicyRequest 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.iam.v1.SetIamPolicyRequest. 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::iam::v1::Policy >

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

TestIamPermissions(std::string const &, std::vector< std::string > const &, Options)

Returns permissions that a caller has on a Queue.

If the resource does not exist, this will return an empty set of permissions, not a [NOT_FOUND][google.rpc.Code.NOT_FOUND] error.

Note: This operation is designed to be used for building permission-aware UIs and command-line tools, not for authorization checking. This operation may "fail open" without warning.

Parameters
Name Description
resource std::string const &

REQUIRED: The resource for which the policy detail is being requested. See the operation documentation for the appropriate value for this field.

permissions std::vector< std::string > const &

The set of permissions to check for the resource. Permissions with wildcards (such as '' or 'storage.') are not allowed. For more information see IAM Overview.

opts Options

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

Returns
Type Description
StatusOr< google::iam::v1::TestIamPermissionsResponse >

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

TestIamPermissions(google::iam::v1::TestIamPermissionsRequest const &, Options)

Returns permissions that a caller has on a Queue.

If the resource does not exist, this will return an empty set of permissions, not a [NOT_FOUND][google.rpc.Code.NOT_FOUND] error.

Note: This operation is designed to be used for building permission-aware UIs and command-line tools, not for authorization checking. This operation may "fail open" without warning.

Parameters
Name Description
request google::iam::v1::TestIamPermissionsRequest 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.iam.v1.TestIamPermissionsRequest. 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::iam::v1::TestIamPermissionsResponse >

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

ListTasks(std::string const &, Options)

Lists the tasks in a queue.

By default, only the BASIC view is retrieved due to performance considerations; response_view controls the subset of information which is returned.

The tasks may be returned in any order. The ordering may change at any time.

Parameters
Name Description
parent std::string const &

Required. The queue name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
opts Options

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

Returns
Type Description
StreamRange< google::cloud::tasks::v2::Task >

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.cloud.tasks.v2.Task, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

ListTasks(google::cloud::tasks::v2::ListTasksRequest, Options)

Lists the tasks in a queue.

By default, only the BASIC view is retrieved due to performance considerations; response_view controls the subset of information which is returned.

The tasks may be returned in any order. The ordering may change at any time.

Parameters
Name Description
request google::cloud::tasks::v2::ListTasksRequest

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.cloud.tasks.v2.ListTasksRequest. 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::cloud::tasks::v2::Task >

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.cloud.tasks.v2.Task, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

GetTask(std::string const &, Options)

Gets a task.

After a task is successfully executed or has exhausted its retry attempts, the task is deleted. A GetTask request for a deleted task returns a NOT_FOUND error.

Parameters
Name Description
name std::string const &

Required. The task name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Task >

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

GetTask(google::cloud::tasks::v2::GetTaskRequest const &, Options)

Gets a task.

After a task is successfully executed or has exhausted its retry attempts, the task is deleted. A GetTask request for a deleted task returns a NOT_FOUND error.

Parameters
Name Description
request google::cloud::tasks::v2::GetTaskRequest 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.cloud.tasks.v2.GetTaskRequest. 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::cloud::tasks::v2::Task >

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

CreateTask(std::string const &, google::cloud::tasks::v2::Task const &, Options)

Creates a task and adds it to a queue.

Tasks cannot be updated after creation; there is no UpdateTask command.

  • The maximum task size is 100KB.
Parameters
Name Description
parent std::string const &

Required. The queue name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
The queue must already exist.

task google::cloud::tasks::v2::Task const &

Required. The task to add.
For more information, see CreateTaskRequest.

opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Task >

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

CreateTask(google::cloud::tasks::v2::CreateTaskRequest const &, Options)

Creates a task and adds it to a queue.

Tasks cannot be updated after creation; there is no UpdateTask command.

  • The maximum task size is 100KB.
Parameters
Name Description
request google::cloud::tasks::v2::CreateTaskRequest 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.cloud.tasks.v2.CreateTaskRequest. 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::cloud::tasks::v2::Task >

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

BatchCreateTasks(std::string const &, std::vector< google::cloud::tasks::v2::CreateTaskRequest > const &, Options)

Creates a batch of tasks and adds them to a queue.

All tasks must be for the same queue. A maximum of 100 tasks can be created in a single batch.

Parameters
Name Description
parent std::string const &

Required. The queue name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
The queue must already exist.

requests std::vector< google::cloud::tasks::v2::CreateTaskRequest > const &

Required. The list of requests to create tasks. The queue specified in parent field of each CreateTaskRequest will be the same. This validation happens on the client side as well as in the handler. BatchCreateTasksRequest.parent will also be the same value as the individual CreateTaskRequest.parent. The maximum number of requests is 100.

opts Options

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

Returns
Type Description
future< StatusOr< google::cloud::tasks::v2::BatchCreateTasksResponse > >

A future that becomes satisfied when the LRO (Long Running Operation) completes or the polling policy in effect for this call is exhausted. The future is satisfied with an error if the LRO completes with an error or the polling policy is exhausted. In this case the StatusOr returned by the future contains the error. If the LRO completes successfully the value of the future contains the LRO's result. For this RPC the result is a google.cloud.tasks.v2.BatchCreateTasksResponse proto message. The C++ class representing this message is created by Protobuf, using the Protobuf mapping rules.

BatchCreateTasks(NoAwaitTag, std::string const &, std::vector< google::cloud::tasks::v2::CreateTaskRequest > const &, Options)

Creates a batch of tasks and adds them to a queue.

Specifying the NoAwaitTag immediately returns the [google::longrunning::Operation] that corresponds to the Long Running Operation that has been started. No polling for operation status occurs.

Parameters
Name Description
NoAwaitTag
parent std::string const &
requests std::vector< google::cloud::tasks::v2::CreateTaskRequest > const &
opts Options
Returns
Type Description
StatusOr< google::longrunning::Operation >

BatchCreateTasks(google::cloud::tasks::v2::BatchCreateTasksRequest const &, Options)

Creates a batch of tasks and adds them to a queue.

All tasks must be for the same queue. A maximum of 100 tasks can be created in a single batch.

Parameters
Name Description
request google::cloud::tasks::v2::BatchCreateTasksRequest 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.cloud.tasks.v2.BatchCreateTasksRequest. 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
future< StatusOr< google::cloud::tasks::v2::BatchCreateTasksResponse > >

A future that becomes satisfied when the LRO (Long Running Operation) completes or the polling policy in effect for this call is exhausted. The future is satisfied with an error if the LRO completes with an error or the polling policy is exhausted. In this case the StatusOr returned by the future contains the error. If the LRO completes successfully the value of the future contains the LRO's result. For this RPC the result is a google.cloud.tasks.v2.BatchCreateTasksResponse proto message. The C++ class representing this message is created by Protobuf, using the Protobuf mapping rules.

BatchCreateTasks(NoAwaitTag, google::cloud::tasks::v2::BatchCreateTasksRequest const &, Options)

Creates a batch of tasks and adds them to a queue.

Specifying the NoAwaitTag immediately returns the [google::longrunning::Operation] that corresponds to the Long Running Operation that has been started. No polling for operation status occurs.

Parameters
Name Description
NoAwaitTag
request google::cloud::tasks::v2::BatchCreateTasksRequest const &
opts Options
Returns
Type Description
StatusOr< google::longrunning::Operation >

BatchCreateTasks(google::longrunning::Operation const &, Options)

Creates a batch of tasks and adds them to a queue.

This method accepts a google::longrunning::Operation that corresponds to a previously started Long Running Operation (LRO) and polls the status of the LRO in the background.

Parameters
Name Description
operation google::longrunning::Operation const &
opts Options
Returns
Type Description
future< StatusOr< google::cloud::tasks::v2::BatchCreateTasksResponse > >

DeleteTask(std::string const &, Options)

Deletes a task.

A task can be deleted if it is scheduled or dispatched. A task cannot be deleted if it has executed successfully or permanently failed.

Parameters
Name Description
name std::string const &

Required. The task name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID
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.

DeleteTask(google::cloud::tasks::v2::DeleteTaskRequest const &, Options)

Deletes a task.

A task can be deleted if it is scheduled or dispatched. A task cannot be deleted if it has executed successfully or permanently failed.

Parameters
Name Description
request google::cloud::tasks::v2::DeleteTaskRequest 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.cloud.tasks.v2.DeleteTaskRequest. 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.

BatchDeleteTasks(std::string const &, std::vector< std::string > const &, Options)

Deletes a batch of tasks.

This is a non-atomic operation: if deletion fails for some tasks, it can still succeed for others. The metadata field of google.longrunning.Operation contains details of failed deletions. A maximum of 1000 tasks can be deleted in a batch.

Parameters
Name Description
parent std::string const &

Required. The queue name. For example: Format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
names std::vector< std::string > const &

Required. The names of the tasks to delete. A maximum of 1000 tasks can be deleted in a batch. For example: Format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID
opts Options

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

Returns
Type Description
future< StatusOr< google::cloud::tasks::v2::BatchDeleteTasksMetadata > >

A future that becomes satisfied when the LRO (Long Running Operation) completes or the polling policy in effect for this call is exhausted. The future is satisfied with an error if the LRO completes with an error or the polling policy is exhausted. In this case the StatusOr returned by the future contains the error. If the LRO completes successfully the value of the future contains the LRO's result. For this RPC the result is a google.cloud.tasks.v2.BatchDeleteTasksMetadata proto message. The C++ class representing this message is created by Protobuf, using the Protobuf mapping rules.

BatchDeleteTasks(NoAwaitTag, std::string const &, std::vector< std::string > const &, Options)

Deletes a batch of tasks.

Specifying the NoAwaitTag immediately returns the [google::longrunning::Operation] that corresponds to the Long Running Operation that has been started. No polling for operation status occurs.

Parameters
Name Description
NoAwaitTag
parent std::string const &
names std::vector< std::string > const &
opts Options
Returns
Type Description
StatusOr< google::longrunning::Operation >

BatchDeleteTasks(google::cloud::tasks::v2::BatchDeleteTasksRequest const &, Options)

Deletes a batch of tasks.

This is a non-atomic operation: if deletion fails for some tasks, it can still succeed for others. The metadata field of google.longrunning.Operation contains details of failed deletions. A maximum of 1000 tasks can be deleted in a batch.

Parameters
Name Description
request google::cloud::tasks::v2::BatchDeleteTasksRequest 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.cloud.tasks.v2.BatchDeleteTasksRequest. 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
future< StatusOr< google::cloud::tasks::v2::BatchDeleteTasksMetadata > >

A future that becomes satisfied when the LRO (Long Running Operation) completes or the polling policy in effect for this call is exhausted. The future is satisfied with an error if the LRO completes with an error or the polling policy is exhausted. In this case the StatusOr returned by the future contains the error. If the LRO completes successfully the value of the future contains the LRO's result. For this RPC the result is a google.cloud.tasks.v2.BatchDeleteTasksMetadata proto message. The C++ class representing this message is created by Protobuf, using the Protobuf mapping rules.

BatchDeleteTasks(NoAwaitTag, google::cloud::tasks::v2::BatchDeleteTasksRequest const &, Options)

Deletes a batch of tasks.

Specifying the NoAwaitTag immediately returns the [google::longrunning::Operation] that corresponds to the Long Running Operation that has been started. No polling for operation status occurs.

Parameters
Name Description
NoAwaitTag
request google::cloud::tasks::v2::BatchDeleteTasksRequest const &
opts Options
Returns
Type Description
StatusOr< google::longrunning::Operation >

BatchDeleteTasks(google::longrunning::Operation const &, Options)

Deletes a batch of tasks.

This method accepts a google::longrunning::Operation that corresponds to a previously started Long Running Operation (LRO) and polls the status of the LRO in the background.

Parameters
Name Description
operation google::longrunning::Operation const &
opts Options
Returns
Type Description
future< StatusOr< google::cloud::tasks::v2::BatchDeleteTasksMetadata > >

RunTask(std::string const &, Options)

Forces a task to run now.

When this method is called, Cloud Tasks will dispatch the task, even if the task is already running, the queue has reached its RateLimits or is PAUSED.

This command is meant to be used for manual debugging. For example, RunTask can be used to retry a failed task after a fix has been made or to manually force a task to be dispatched now.

If Cloud Tasks receives a successful response from the task's target, then the task will be deleted; otherwise the task's schedule_time will be reset to the time that RunTask was called plus the retry delay specified in the queue's RetryConfig.

RunTask returns [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a task that has already succeeded or permanently failed.

Parameters
Name Description
name std::string const &

Required. The task name. For example: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::Task >

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

RunTask(google::cloud::tasks::v2::RunTaskRequest const &, Options)

Forces a task to run now.

When this method is called, Cloud Tasks will dispatch the task, even if the task is already running, the queue has reached its RateLimits or is PAUSED.

This command is meant to be used for manual debugging. For example, RunTask can be used to retry a failed task after a fix has been made or to manually force a task to be dispatched now.

If Cloud Tasks receives a successful response from the task's target, then the task will be deleted; otherwise the task's schedule_time will be reset to the time that RunTask was called plus the retry delay specified in the queue's RetryConfig.

RunTask returns [NOT_FOUND][google.rpc.Code.NOT_FOUND] when it is called on a task that has already succeeded or permanently failed.

Parameters
Name Description
request google::cloud::tasks::v2::RunTaskRequest 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.cloud.tasks.v2.RunTaskRequest. 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::cloud::tasks::v2::Task >

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

UpdateCmekConfig(google::cloud::tasks::v2::CmekConfig const &, google::protobuf::FieldMask const &, Options)

Creates or Updates a CMEK config.

Updates the Customer Managed Encryption Key associated with the Cloud Tasks location (Creates if the key does not already exist). All new tasks created in the location will be encrypted at-rest with the KMS-key provided in the config.

Parameters
Name Description
cmek_config google::cloud::tasks::v2::CmekConfig const &

Required. The config to update. Its name attribute distinguishes it.

update_mask google::protobuf::FieldMask const &

List of fields to be updated in this request.

opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::CmekConfig >

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

UpdateCmekConfig(google::cloud::tasks::v2::UpdateCmekConfigRequest const &, Options)

Creates or Updates a CMEK config.

Updates the Customer Managed Encryption Key associated with the Cloud Tasks location (Creates if the key does not already exist). All new tasks created in the location will be encrypted at-rest with the KMS-key provided in the config.

Parameters
Name Description
request google::cloud::tasks::v2::UpdateCmekConfigRequest 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.cloud.tasks.v2.UpdateCmekConfigRequest. 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::cloud::tasks::v2::CmekConfig >

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

GetCmekConfig(std::string const &, Options)

Gets the CMEK config.

Gets the Customer Managed Encryption Key configured with the Cloud Tasks location. By default there is no kms_key configured.

Parameters
Name Description
name std::string const &

Required. The config. For example: projects/PROJECT_ID/locations/LOCATION_ID/CmekConfig
opts Options

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

Returns
Type Description
StatusOr< google::cloud::tasks::v2::CmekConfig >

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

GetCmekConfig(google::cloud::tasks::v2::GetCmekConfigRequest const &, Options)

Gets the CMEK config.

Gets the Customer Managed Encryption Key configured with the Cloud Tasks location. By default there is no kms_key configured.

Parameters
Name Description
request google::cloud::tasks::v2::GetCmekConfigRequest 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.cloud.tasks.v2.GetCmekConfigRequest. 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::cloud::tasks::v2::CmekConfig >

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

ListLocations(google::cloud::location::ListLocationsRequest, Options)

Lists information about the supported locations for this service.

Parameters
Name Description
request google::cloud::location::ListLocationsRequest

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.cloud.location.ListLocationsRequest. 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::cloud::location::Location >

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.cloud.location.Location, or rather, the C++ class generated by Protobuf from that type. Please consult the Protobuf documentation for details on the Protobuf mapping rules.

GetLocation(google::cloud::location::GetLocationRequest const &, Options)

Gets information about a location.

Parameters
Name Description
request google::cloud::location::GetLocationRequest 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.cloud.location.GetLocationRequest. 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::cloud::location::Location >

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

GetOperation(std::string const &, Options)

Gets the latest state of a long-running operation.

Clients can use this method to poll the operation result at intervals as recommended by the API service.

Parameters
Name Description
name std::string const &

The name of the operation resource.

opts Options

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

Returns
Type Description
StatusOr< google::longrunning::Operation >

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

GetOperation(google::longrunning::GetOperationRequest const &, Options)

Gets the latest state of a long-running operation.

Clients can use this method to poll the operation result at intervals as recommended by the API service.

Parameters
Name Description
request google::longrunning::GetOperationRequest 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.longrunning.GetOperationRequest. 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::longrunning::Operation >

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