Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
Enables an application to queue background work. Work is done through webhooks that process tasks pushed from a push queue, or workers that manually pull tasks from a pull queue.
In push queues, Tasks execute in best-effort order of ETA. Webhooks that fail cause tasks to be retried at a later time. You can configure the rate and number of retries for failed tasks. You can specify webhook URLs directly for push tasks. You can also use the default URL scheme, which translates task names into URLs relative to a queue's base path. A default queue is also provided for simple usage.
In pull queues, workers are responsible for leasing tasks, processing them, and deleting them after processing. You can configure the number of task retries, which is based on how many times the task has been leased. You can define multiple queues with independent throttling controls.
Task
is provided by the google.appengine.api.taskqueue
module.
The Task class encapsulates a description of offline work in a push queue or a pull queue. In push queues, this work is modeled as a web hook and includes a URL endpoint in your application, and an optional task payload.
In pull queues, the task's payload is fetched from the queue by the task consumer when the task is leased.
You set the various properties for a task in the constructor. Once the Task object is instantiated, you insert that task into a queue. A Task instance can be inserted into one queue only.
Instantiates a Task object which describes a unit of offline work. The instance may be inserted into a push or pull queue for processing based on the requirements of the application.
All arguments are optional. Some arguments have different meanings in push queues and pull queues. The following table summarizes the meaning of each argument in each type of queue.
Task class argument | Description | Functionality in Push Queues | Functionality in Pull Queues |
---|---|---|---|
|
The data payload providing the parameters for this task's work. Allowed only for |
Payload is delivered to the webhook or backend in the body of an HTTP request. |
Payload is fetched by workers as part of the response from lease_tasks(). |
|
The task's name. |
If you don't specify a task name, App Engine auto-generates the name when your application adds the task to a queue. |
If you don't specify a task name, App Engine auto-generates the name when your application adds the task to a queue. |
|
The method of task execution. May be |
Do not specify a |
Set the |
|
URL for the webhook that should handle this task. |
The If you are using backends, you can specify the URL of the instance and backend that you want to perform the work. |
Do not specify a |
|
Dictionary of headers to pass to the webhook. |
Values in the dictionary may be iterable to indicate repeated header fields. If a |
Do not specify |
|
Dictionary of parameters to use for this task. |
Values in the dictionary may be iterable to indicate repeated parameters. In
In
|
Values in the dictionary may be iterable to indicate repeated parameters. In
|
|
Minimum time to wait before executing this task, in seconds. Defaults to zero. Do not specify a countdown if you specified an |
Minimum time to wait before executing this task, in seconds. |
Designates how long to wait, in seconds, before allowing the task to be leased. |
|
Earliest time of task execution. If None, defaults to now. |
Earliest time to execute the task. May be timezone-aware or timezone-naive. |
Designates the earliest time that a worker can lease a task. No worker can lease a task before the |
|
TaskRetryOptions used to retry failed tasks. |
Includes |
Only the |
|
The alternate application version, or backend, on which to execute this task. |
No push-specific details. |
No pull-specific details. |
The following table describes properties of a Task instance. These properties differ slightly in push and pull queues, as described in the following table:
Task instance property | Meaning for Push Tasks | Meaning for Pull Tasks | |
---|---|---|---|
|
A datetime.datetime object which provides the earliest time when this task will execute. |
A datetime.datetime object representing the earliest time this task can be leased. |
|
|
A POSIX timestamp giving an estimate of when this task will execute. |
A POSIX timestamp representing the earliest time this task can be leased. |
|
|
The HTTP headers which will be used when invoking this task. |
Not applicable |
|
|
The HTTP method used to invoke this task, one of |
PULL only. All other methods are illegal for pull tasks. |
|
|
The name of this task. Will be |
The name of this task. Will be |
|
|
True if this task will run on the queue's default URL; false if not. |
Not applicable |
|
|
The payload which will be used when invoking this task; may be None. |
The payload which will be used when invoking this task; may be None. |
|
|
Size of this task in bytes. |
Size of this task in bytes. |
|
|
The number of times this task has been retried. |
The number of times this task has been leased. |
|
|
Any or all of the TaskRetryOptions for this task, which may be None. |
May be only the |
|
|
None. |
The tag for this task. You can enqueue tasks by tag in pull queues using |
|
|
Returns the version of the application to which this task was targeted. |
No push-specific details. |
No pull-specific details. |
url
The URL handler for this task relative to your application's root directory.
Pull queues have no url.
was_deleted
True if this task has been successfully deleted.
True if this task has been successfully deleted.
was_enqueued
Not queue specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.
Not queue specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.
A Task instance has the following methods:
Adds this task to a queue. The queue is specified by name. A single Task instance may only be added to one queue.
Arguments:
The return value is the task itself.
Returns a dictionary of strings mapping parameter names to their values as strings. If the same name parameter has several values, then the value is a list of strings. For POST
and PULL
requests,, the parameters are extracted from the task payload; for all other methods, the parameters are extracted from the URL query string.
Raises a ValueError if:
PULL
or POST
does not contain application/x-www-form-urlencoded
data.