Tasks

A Task resource represents a single task to be handled by a client. A task is defined by an arbitrary blob of data that should be understood by the client.

The standard usage is that a client calls task.lease to get the next available task, performs that task, and then calls task.delete on that task before the lease expires. If the client cannot finish the task before the lease expires, and has a reasonable chance of completing the task, it should call task.update before the lease expires. If the client completes the task after the lease has expired, it still needs to delete the task. Tasks should be designed to be idempotent to avoid errors if multiple clients complete the same task.

For a list of methods for this resource, see the end of this page.

Resource representations

{
  "kind": "taskqueues#task",
  "id": string,
  "queueName": string,
  "payloadBase64": string,
  "enqueueTimestamp": long,
  "leaseTimestamp": long,
  "retry_count": integer,
  "tag": string
}

Property name	Value	Description
`enqueueTimestamp`	`long`	[Not mutable.] Time (in microseconds since the epoch) at which the task was enqueued.
`id`	`string`	Randomly generated name of the task. You may override the default generated name by specifying your own name when inserting the task. We strongly recommend against specifying a task name yourself.
`kind`	`string`	[Not mutable.] The kind of object returned, in this case set to `task`.
`leaseTimestamp`	`long`	The time at which the task lease will expire, in microseconds since the epoch. If this task has never been leased, it will be zero. If this this task has been previously leased and the lease has expired, this value will be < Now(). On task.insert, this must be set to the time at which the task will first be available for lease. On task.lease, this property is not mutable and reflects the time at which the task lease will expire.
`payloadBase64`	`string`	[Not mutable.] The bytes describing the task to perform. This is a base64-encoded string. The client is expected to understand the payload format. The maximum size is 1MB. This value will be empty in calls to `tasks.list`. Required for calls to `tasks.insert`.
`queueName`	`string`	[Not mutable.] Name of the queue that the task is in. Required for calls to `tasks.insert`.
`retry_count`	`integer`	The number of leases applied to this task.
`tag`	`string`	The tag for this task. Tagging tasks allows you to group them for processing using `lease.group_by_tag`.

Methods

delete
Deletes a task from a TaskQueue.

get
Gets the named task in a TaskQueue.

insert
Insert a task into an existing queue.

lease
Acquires a lease on the topmost N unowned tasks in the specified queue.

list
Lists all non-deleted Tasks in a TaskQueue, whether or not they are currently leased, up to a maximum of 100.

patch
Update tasks that are leased out of a TaskQueue.

update
Update the duration of a task lease.

10 April 2024