Class CloudTasksClient (2.31.0)

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, a queue with the same name can't be created for 7 days.

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, a queue with the same name can't be created for 7 days.

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.

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.

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.

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.

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.

The dispatched task is returned. That is, the task that is returned contains the [status][Task.status] after the task is dispatched but before the task is received by its target.

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.

The dispatched task is returned. That is, the task that is returned contains the [status][Task.status] after the task is dispatched but before the task is received by its target.

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.

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.