tasks

Creates, updates, deletes, gets or lists a tasks resource.

Overview

Name	tasks
Type	Resource
Id	google.cloudtasks.tasks

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	Optionally caller-specified in CreateTask. The task name. The task name must have the following format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID * PROJECT_ID can contain letters ([A-Za-z]), numbers ([0-9]), hyphens (-), colons (:), or periods (.). For more information, see Identifying projects * LOCATION_ID is the canonical ID for the task's location. The list of available locations can be obtained by calling ListLocations. For more information, see https://cloud.google.com/about/locations/. * QUEUE_ID can contain letters ([A-Za-z]), numbers ([0-9]), or hyphens (-). The maximum length is 100 characters. * TASK_ID can contain only letters ([A-Za-z]), numbers ([0-9]), hyphens (-), or underscores (_). The maximum length is 500 characters.
appEngineHttpRequest	object	HTTP request that is sent to the App Engine app handler. An App Engine task is a task that has AppEngineHttpRequest set. (id: AppEngineHttpRequest)
createTime	string (google-datetime)	Output only. The time that the task was created. create_time will be truncated to the nearest second.
dispatchCount	integer (int32)	Output only. The number of attempts dispatched. This count includes attempts which have been dispatched but haven't received a response.
dispatchDeadline	string (google-duration)	The deadline for requests sent to the worker. If the worker does not respond by this deadline then the request is cancelled and the attempt is marked as a DEADLINE_EXCEEDED failure. Cloud Tasks will retry the task according to the RetryConfig. Note that when the request is cancelled, Cloud Tasks will stop listening for the response, but whether the worker stops processing depends on the worker. For example, if the worker is stuck, it may not react to cancelled requests. The default and maximum values depend on the type of request: * For HTTP tasks, the default is 10 minutes. The deadline must be in the interval [15 seconds, 30 minutes]. * For App Engine tasks, 0 indicates that the request has the default deadline. The default deadline depends on the scaling type of the service: 10 minutes for standard apps with automatic scaling, 24 hours for standard apps with manual and basic scaling, and 60 minutes for flex apps. If the request deadline is set, it must be in the interval [15 seconds, 24 hours 15 seconds]. Regardless of the task's dispatch_deadline, the app handler will not run for longer than than the service's timeout. We recommend setting the dispatch_deadline to at most a few seconds more than the app handler's timeout. For more information see Timeouts. The value must be given as a string that indicates the length of time (in seconds) followed by s (for "seconds"). For more information on the format, see the documentation for Duration. dispatch_deadline will be truncated to the nearest millisecond. The deadline is an approximate deadline.
firstAttempt	object	Output only. The status of the task's first attempt. Only dispatch_time will be set. The other Attempt information is not retained by Cloud Tasks. (id: Attempt)
httpRequest	object	HTTP request that is sent to the worker. An HTTP task is a task that has HttpRequest set. (id: HttpRequest)
lastAttempt	object	Output only. The status of the task's last attempt. (id: Attempt)
responseCount	integer (int32)	Output only. The number of attempts which have received a response.
scheduleTime	string (google-datetime)	The time when the task is scheduled to be attempted or retried. schedule_time will be truncated to the nearest microsecond.
view	string	Output only. The view specifies which subset of the Task has been returned. (VIEW_UNSPECIFIED, BASIC, FULL)

list

Name	Datatype	Description
name	string	Optionally caller-specified in CreateTask. The task name. The task name must have the following format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID * PROJECT_ID can contain letters ([A-Za-z]), numbers ([0-9]), hyphens (-), colons (:), or periods (.). For more information, see Identifying projects * LOCATION_ID is the canonical ID for the task's location. The list of available locations can be obtained by calling ListLocations. For more information, see https://cloud.google.com/about/locations/. * QUEUE_ID can contain letters ([A-Za-z]), numbers ([0-9]), or hyphens (-). The maximum length is 100 characters. * TASK_ID can contain only letters ([A-Za-z]), numbers ([0-9]), hyphens (-), or underscores (_). The maximum length is 500 characters.
appEngineHttpRequest	object	HTTP request that is sent to the App Engine app handler. An App Engine task is a task that has AppEngineHttpRequest set. (id: AppEngineHttpRequest)
createTime	string (google-datetime)	Output only. The time that the task was created. create_time will be truncated to the nearest second.
dispatchCount	integer (int32)	Output only. The number of attempts dispatched. This count includes attempts which have been dispatched but haven't received a response.
dispatchDeadline	string (google-duration)	The deadline for requests sent to the worker. If the worker does not respond by this deadline then the request is cancelled and the attempt is marked as a DEADLINE_EXCEEDED failure. Cloud Tasks will retry the task according to the RetryConfig. Note that when the request is cancelled, Cloud Tasks will stop listening for the response, but whether the worker stops processing depends on the worker. For example, if the worker is stuck, it may not react to cancelled requests. The default and maximum values depend on the type of request: * For HTTP tasks, the default is 10 minutes. The deadline must be in the interval [15 seconds, 30 minutes]. * For App Engine tasks, 0 indicates that the request has the default deadline. The default deadline depends on the scaling type of the service: 10 minutes for standard apps with automatic scaling, 24 hours for standard apps with manual and basic scaling, and 60 minutes for flex apps. If the request deadline is set, it must be in the interval [15 seconds, 24 hours 15 seconds]. Regardless of the task's dispatch_deadline, the app handler will not run for longer than than the service's timeout. We recommend setting the dispatch_deadline to at most a few seconds more than the app handler's timeout. For more information see Timeouts. The value must be given as a string that indicates the length of time (in seconds) followed by s (for "seconds"). For more information on the format, see the documentation for Duration. dispatch_deadline will be truncated to the nearest millisecond. The deadline is an approximate deadline.
firstAttempt	object	Output only. The status of the task's first attempt. Only dispatch_time will be set. The other Attempt information is not retained by Cloud Tasks. (id: Attempt)
httpRequest	object	HTTP request that is sent to the worker. An HTTP task is a task that has HttpRequest set. (id: HttpRequest)
lastAttempt	object	Output only. The status of the task's last attempt. (id: Attempt)
responseCount	integer (int32)	Output only. The number of attempts which have received a response.
scheduleTime	string (google-datetime)	The time when the task is scheduled to be attempted or retried. schedule_time will be truncated to the nearest microsecond.
view	string	Output only. The view specifies which subset of the Task has been returned. (VIEW_UNSPECIFIED, BASIC, FULL)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, queuesId, tasksId	responseView	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.
list	select	projectsId, locationsId, queuesId	pageSize, pageToken, responseView	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.
create	insert	projectsId, locationsId, queuesId		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.
delete	delete	projectsId, locationsId, queuesId, tasksId		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.
buffer	exec	projectsId, locationsId, queuesId, taskId		Creates and buffers a new task without the need to explicitly define a Task message. The queue must have HTTP target. To create the task with a custom ID, use the following format and set TASK_ID to your desired ID: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID:buffer To create the task with an automatically generated ID, use the following format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks:buffer.
run	exec	projectsId, locationsId, queuesId, tasksId		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 when it is called on a task that has already succeeded or permanently failed.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
locationsId	string
projectsId	string
queuesId	string
taskId	string
tasksId	string
pageSize	integer (int32)
pageToken	string
responseView	string

SELECT examples

get

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.

SELECT
name,
appEngineHttpRequest,
createTime,
dispatchCount,
dispatchDeadline,
firstAttempt,
httpRequest,
lastAttempt,
responseCount,
scheduleTime,
view
FROM google.cloudtasks.tasks
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND queuesId = '{{ queuesId }}' -- required
AND tasksId = '{{ tasksId }}' -- required
AND responseView = '{{ responseView }}'
;

list

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.

SELECT
name,
appEngineHttpRequest,
createTime,
dispatchCount,
dispatchDeadline,
firstAttempt,
httpRequest,
lastAttempt,
responseCount,
scheduleTime,
view
FROM google.cloudtasks.tasks
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND queuesId = '{{ queuesId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND responseView = '{{ responseView }}'
;

INSERT examples

create

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.

INSERT INTO google.cloudtasks.tasks (
data__responseView,
data__task,
projectsId,
locationsId,
queuesId
)
SELECT 
'{{ responseView }}',
'{{ task }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ queuesId }}'
RETURNING
name,
appEngineHttpRequest,
createTime,
dispatchCount,
dispatchDeadline,
firstAttempt,
httpRequest,
lastAttempt,
responseCount,
scheduleTime,
view
;

Manifest

# Description fields are for documentation purposes
- name: tasks
props:
  - name: projectsId
    value: "{{ projectsId }}"
    description: Required parameter for the tasks resource.
  - name: locationsId
    value: "{{ locationsId }}"
    description: Required parameter for the tasks resource.
  - name: queuesId
    value: "{{ queuesId }}"
    description: Required parameter for the tasks resource.
  - name: responseView
    value: "{{ responseView }}"
    description: |
      The response_view specifies which subset of the Task will be returned. By default response_view is BASIC; not all information is retrieved by default because some data, such as payloads, might be desirable to return only when needed because of its large size or because of the sensitivity of data that it contains. Authorization for FULL requires `cloudtasks.tasks.fullView` [Google IAM](https://cloud.google.com/iam/) permission on the Task resource.
    valid_values: ['VIEW_UNSPECIFIED', 'BASIC', 'FULL']
  - name: task
    description: |
      Required. The task to add. Task names have the following format: `projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID`. The user can optionally specify a task name. If a name is not specified then the system will generate a random unique task id, which will be set in the task returned in the response. If schedule_time is not set or is in the past then Cloud Tasks will set it to the current time. Task De-duplication: Explicitly specifying a task ID enables task de-duplication. If a task's ID is identical to that of an existing task or a task that was deleted or executed recently then the call will fail with ALREADY_EXISTS. The IDs of deleted tasks are not immediately available for reuse. It can take up to 24 hours (or 9 days if the task's queue was created using a queue.yaml or queue.xml) for the task ID to be released and made available again. Because there is an extra lookup cost to identify duplicate task names, these CreateTask calls have significantly increased latency. Using hashed strings for the task id or for the prefix of the task id is recommended. Choosing task ids that are sequential or have sequential prefixes, for example using a timestamp, causes an increase in latency and error rates in all task commands. The infrastructure relies on an approximately uniform distribution of task ids to store and serve tasks efficiently.
    value:
      lastAttempt:
        scheduleTime: "{{ scheduleTime }}"
        dispatchTime: "{{ dispatchTime }}"
        responseTime: "{{ responseTime }}"
        responseStatus:
          code: {{ code }}
          message: "{{ message }}"
          details: "{{ details }}"
      appEngineHttpRequest:
        relativeUri: "{{ relativeUri }}"
        body: "{{ body }}"
        appEngineRouting:
          version: "{{ version }}"
          host: "{{ host }}"
          service: "{{ service }}"
          instance: "{{ instance }}"
        httpMethod: "{{ httpMethod }}"
        headers: "{{ headers }}"
      firstAttempt:
        scheduleTime: "{{ scheduleTime }}"
        dispatchTime: "{{ dispatchTime }}"
        responseTime: "{{ responseTime }}"
        responseStatus:
          code: {{ code }}
          message: "{{ message }}"
          details: "{{ details }}"
      responseCount: {{ responseCount }}
      view: "{{ view }}"
      httpRequest:
        headers: "{{ headers }}"
        httpMethod: "{{ httpMethod }}"
        oauthToken:
          serviceAccountEmail: "{{ serviceAccountEmail }}"
          scope: "{{ scope }}"
        body: "{{ body }}"
        url: "{{ url }}"
        oidcToken:
          serviceAccountEmail: "{{ serviceAccountEmail }}"
          audience: "{{ audience }}"
      name: "{{ name }}"
      scheduleTime: "{{ scheduleTime }}"
      dispatchCount: {{ dispatchCount }}
      createTime: "{{ createTime }}"
      dispatchDeadline: "{{ dispatchDeadline }}"

DELETE examples

delete

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.

DELETE FROM google.cloudtasks.tasks
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND queuesId = '{{ queuesId }}' --required
AND tasksId = '{{ tasksId }}' --required
;

Lifecycle Methods

buffer

Creates and buffers a new task without the need to explicitly define a Task message. The queue must have HTTP target. To create the task with a custom ID, use the following format and set TASK_ID to your desired ID: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID:buffer To create the task with an automatically generated ID, use the following format: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks:buffer.

EXEC google.cloudtasks.tasks.buffer 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@queuesId='{{ queuesId }}' --required, 
@taskId='{{ taskId }}' --required 
@@json=
'{
"body": "{{ body }}"
}'
;

run

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 when it is called on a task that has already succeeded or permanently failed.

EXEC google.cloudtasks.tasks.run 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@queuesId='{{ queuesId }}' --required, 
@tasksId='{{ tasksId }}' --required 
@@json=
'{
"responseView": "{{ responseView }}"
}'
;