English

Google App Engine

Task Queue REST API Reference Experimental!

The following table summarizes the REST methods exposed by the Google Task Queue API.

Resource Method REST URI relative to https://www.googleapis.com/taskqueue/v1beta1
TaskQueue Get GET .../projects/projectname/taskqueues/queuename
Task List GET .../projects/projectname/taskqueues/queuename/tasks
Get GET .../projects/projectname/taskqueues/queuename/tasks/taskname
Delete DELETE .../projects/projectname/taskqueues/queuename/tasks/taskname
Lease POST .../projects/projectname/taskqueues/queuename/lease

TaskQueue Resource

A TaskQueue resource represents a queue created by an App Engine application. You create TaskQueue resources within a project namespace defined by your App Engine App ID. You can use the TaskQueue resource to get information about a queue. By default, a user has no rights on a TaskQueue unless they are explicitly granted rights in queues.yaml.

Each project can hold an unlimited number of TaskQueue resources. It is currently not possible to create, modify, or delete queues using the REST API.

TaskQueue Resource Description

JSON

{
  "kind": "taskqueues#taskqueue",
  "id": string,
  "maxLeases": number,
  "stats": {
    "totalTasks": number,
    "oldestTask": number,
    "leasedLastMinute": number,
    "leasedLastHour": number
  }
}
Property Name Value Description Mutable
kind string Identifies the resource type. No
id string The name of the task queue. This name must be unique among all queue names within this project. See the naming restrictions. Required and mutable on insert only
maxLeases number The number of times a client can lease a specific task before it will be automatically dropped from the queue. If not specified, all tasks will be available for indefinite retries. In practice, you should set this value to a reasonably small value so that a difficult task does not block the whole queue. Yes
stats object An object that holds statistics for this queue. No
stats.totalTasks number The total number of tasks in the queue. No
stats.oldestTask number The timestamp of the oldest task in the queue, in seconds since the epoch. No
stats.leasedLastMinute number The number of tasks leased in the last minute. No
stats.leasedLastHour number The number of tasks leased in the last hour. No

TaskQueue Collection Methods

Get TaskQueue

Returns information about a specified TaskQueue resource.

Authentication is required.

Request (REST)

GET
https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}?{QUERY_PARAMS}

Query Parameters:

Name Type Description Required
getStats boolean Whether to populate the stats field of the returned resource. Default value is false. False

Response

Returns a TaskQueue resource.

Task Resource

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 TaskQueue.lease to get the next available task, performs that task, and then calls TaskQueue.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 TaskQueue.lease again 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.

Task Resource Description

JSON

{
  "kind": "taskqueues#task",
  "id": string,
  "queueName": string,
  "payloadBase64": string,
  "enqueueTimestamp": number,
  "leaseTimestamp": number
}
Property Name Value Description Mutable
kind string The type of resource. No
id string The name of the task, which can be specified when inserting the task from App Engine. If not specified, a random name will be generated. We strongly recommend against specifying a task name yourself. Optional, used on insert only
queueName string Name of the TaskQueue that holds this task. No
payloadBase64 string 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. No
enqueueTimestamp number The time when the task was enqueued, in seconds since the epoch. No
leaseTimestamp number The time at which the task lease will expire, in seconds 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(). No

Task Collection Methods

List Tasks

Lists all undeleted Tasks in a TaskQueue, whether or not they are currently leased, up to a maximum of 100. The retrieved tasks will not include the task payload. Deleted tasks take up to three days to appear in this list, and the names of these tasks are unavailable until they appear here. Tasks are returned in the same order they are stored on the queue.

Authentication is required.

Request (REST)

GET
https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks

Response (JSON)

An array of tasks, as shown here:

{
  "kind": "taskqueues#tasks",
  "items": [
    Task resource array
  ]
}

Get Task

Gets the named task in a TaskQueue. This does not lease the task. You shouldn't need to call this method in your typical work flow.

Authentication is required.

Request (REST)

GET
https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/{TASK_NAME}

Response

The requested Task resource.

Delete Task

Deletes a task from a TaskQueue. You should only call this method if you own the lease for a task and have completed it, unless you have some other compelling reason to remove a task from the queue.

Authentication is required.

Request (REST)

DELETE
https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/{TASK_NAME}

Response

An HTTP 200 response if successful, or an HTTP error code on failure.

Lease Task

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

Authentication is required.

Request (REST)

POST
https://www.googleapis.com/taskqueue/v1beta1/projects/{PROJECT_NAME}/taskqueues/{TASKQUEUE_NAME}/tasks/lease?{QUERY_PARAMS}

Query Parameters:

Name Type Description Required
leaseSecs integer How long to lease this task, in seconds. True
numTasks integer How many tasks to lease. True

Response

An array of leased Task resources, as shown here:

{
  "kind": "taskqueues#tasks",
  "items": [
    Task resource array
  ]
}