Google App Engine

The Task Class

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
  4. Instance methods:

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:

Task instance property Meaning for Push Tasks Meaning for Pull Tasks

eta

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.

eta_posix

A POSIX timestamp giving an estimate of when this task will execute.

A POSIX timestamp representing the earliest time this task can be leased.

headers

The HTTP headers which will be used when invoking this task.

Not applicable

method

The HTTP method used to invoke this task, one of GET, POST, HEAD, PUT, or DELETE.

PULL only. All other methods are illegal for pull tasks.

name

The name of this task. Will be None if using auto-assigned task names and this task has not yet been added to a queue.

The name of this task. Will be None if using auto-assigned task names and this task has not yet been added to a queue.

on_queue_url

True if this task will run on the queue's default URL; false if not.

Not applicable

payload

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

Size of this task in bytes.

Size of this task in bytes.

retry_count

The number of times this task has been retried.

The number of times this task has been leased.

retry_options

Any or all of the TaskRetryOptions for this task, which may be None.

May be only the task_retry_limit parameter of the TaskRetryOptions class, or None.

tag

None.

The tag for this task. You can enqueue tasks by tag in pull queues using Queue.lease_tasks_by_tag().

target

The version of the application to which this task was targeted.

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 push-specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.

Not pull-specific. True if this task has been inserted into a queue. Does not check if this task already exists in the queue.

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.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.