Google App Engine

Functions

The google.appengine.api.taskqueue package provides the following functions:

add(*args, **kwargs)

Convenience method that creates a task and adds it to the default queue or a specified queue.

Arguments

*args, **kwargs
Passed to the Task class to create a new instance. All arguments are optional.
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().

queue_name

Name of the queue in which to insert the task. If unspecified, defaults to the default queue.

No specific functionality for push queues.

No specific functionality for pull queues.

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.

transactional

A Boolean argument. If False, adds the task to a queue whether the enclosing transaction succeeds or fails. If True, raises an exception if called outside a transaction. This argument is optional.

No specific functionality for push queues.

No specific functionality for pull queues.

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.

Result value

The task that was added to the queue.
create_rpc(deadline=None, callback=None)

Creates a Task Queue RPC object that can be used for async calls.

Arguments

deadline
Optional deadline in seconds for the RPC object. For example, if you specify a deadline of 9 seconds, then wait 2 seconds before calling get_result(), the get_result() function will wait a maximum of 7 seconds before throwing DeadlineExceededError. This is useful in cases where an application makes a sequence of async calls and then waits for them to complete.
callback
An optional function to be called when the Task Queue service returns results successfully. The function is called without arguments. The callback function is called when get_result(), or check_success(), or wait() is invoked on the RPC object.

The callback function does not get called in a background process or thread; it only gets called when one of the above RPC methods is called by the application.

The callback function is called even if the request fails or the RPC deadline elapses.

Exceptions

BadTransactionStateError

The transactional argument is true but this call is being made outside a transaction.

InvalidEtaError

The eta argument is more than 30 days after the current date.

InvalidQueueModeError

A task with method PULL is being added to a push queue, or a task with a method not equal to PULL is being added to a pull queue.

InvalidTagError

The specified tag is too long.

InvalidTaskError

Any specified parameter is invalid.

InvalidTaskNameError

The task name is invalid.

InvalidUrlError

The task URL is invalid or too long.

TaskTooLargeError

The task and associated payload are too large.

TransactionalRequestTooLargeError

The tasks transactional value is True and the total size of the tasks and supporting request data exceeds the MAX_TRANSACTIONAL_REQUEST_SIZE_BYTES quota.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.