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.

1. Introduction
2. Task()
3. Properties
   • eta
   • eta_posix
   • headers
   • method
   • name
   • on_queue_url
   • payload
   • size
   • retry_count
   • retry_options
   • tag
   • target
   • url
   • was_enqueued
   • was_deleted
4. Instance methods:
   • add()
   • add_async()
   • extract_params()

Introduction

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.

Constructor

class Task ( payload =None, ** kw )

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.

Argument	Description	Functionality in Push Queues	Functionality in Pull Queues
payload	The data payload providing the parameters for this task's work. Allowed only for POST, PUT, and PULL methods.	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() .
name	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.
method	The method of task execution. May be POST (default), GET, PUT, DELETE, HEAD, or PULL.	Do not specify a method for push tasks. This argument defaults to POST, which posts assigned tasks to the web hook at the specified url .	Set the method to PULL. This setting prevents the task from being delivered to the web hook so a worker can be lease it from the pull queue.
url	URL for the webhook that should handle this task.	The url is usually a path relative to your application's root directory. May have a query string unless the method is POST. 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 url for pull queue tasks.
headers	Dictionary of headers to pass to the webhook.	Values in the dictionary may be iterable to indicate repeated header fields. If a Content-Type header is not specified, a default of text/plain is used. If you specify a Host header, do not use the target keyword argument.	Do not specify headers for pull queue tasks.
params	Dictionary of parameters to use for this task.	Values in the dictionary may be iterable to indicate repeated parameters. In POST requests, Do not specify params if you already specified a payload . Params are encoded as application/x-www-form-urlencoded and set to the payload . In PUT requests, Params are converted to a query string if the URL contains a query string, or the task already has a payload . Do not specify params if the URL already contains a query string and the method is GET.	Values in the dictionary may be iterable to indicate repeated parameters. In PULL requests, Do not specify params if you already specified a payload . Params are encoded as application/x-www-form-urlencoded and set to the payload .
countdown	Minimum time to wait before executing this task, in seconds. Defaults to zero. Do not specify a countdown if you specified an eta .	Minimum time to wait before executing this task, in seconds.	Designates how long to wait, in seconds, before allowing the task to be leased.
eta	Earliest time of task execution, in seconds. If None, defaults to now. Must be less than 30 days.	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 eta .
retry_options	A TaskRetryOptions object used to retry failed tasks.	Includes min_backoff_seconds , max_backoff_seconds , task_age_limit , max_doublings , and task_retry_limit .	Only the task_retry_limit option is allowed. It indicates the number of times a task may be leased before it is automatically deleted from the queue.
tag	The tag to be used when grouping the task by tag.	Task tagging is not available in push queues.	For more information about task tagging, use Queue.lease_tasks_by_tag() .
target	A string naming a module/version, a frontend version, or a backend, on which to execute this task. The string is prepended to the domain name of your app. For example, if your app ID is my-app.appspot.com and you set the target to my-version.my-module , the URL hostname will be set to my-version.my-module.my-app.appspot.com . If you set the target keyword argument do not specify a Host header in the dictionary for the headers keyword argument. The target argument is ignored and has no effect if your queue.yaml file also sets a target for the queue.	No push-specific details.	Do not specify target for pull queue tasks.

Properties

The following table describes properties of a Task instance. These properties differ slightly in push and pull queues, as described in the following table:

Instance Methods

A Task instance has the following methods:

add (queue_name ='default' , transactional = False )

Adds this task to a queue. The queue is specified by name. A single Task instance may only be added to one queue.

Arguments

queue_name

Name of the queue to which this task will be added. The name should correspond to a user-created entry in the queue.yaml configuration file. If not supplied, the task will be added to the default queue.

transactional = False

Relevant when this method is called inside db.run_in_transaction() . Indicates that this transactional task should be added only if an enclosing Datastore transaction is committed successfully. Note that this task must not have a user-specified name in this case. Also, you should call get_result on the RPC object before committing the transaction to ensure that the request has finished.

The return value is the task itself.

add_async (queue_name ='default' , transactional = False , rpc = None )

Asynchronously adds this task to a queue. The queue is specified by name. A single Task instance may only be added to one queue.

Arguments

queue_name

Name of the queue to which this task will be added. The name should correspond to a user-created entry in the queue.yaml configuration file. If not supplied, the task will be added to the default queue.

transactional = False

Relevant when this method is called inside db.run_in_transaction() . Indicates that this transactional task should be added only if an enclosing Datastore transaction is committed successfully. Note that this task must not have a user-specified name in this case.

rpc

The RPC object used for the asynchronous operation.

The return value is an RPC object representing the task.

extract_params ()

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:

• The payload for PULL or POST does not contain application/x-www-form-urlencoded data.
• The payload for all other methods does not contain a query.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .