This page describes how to create tasks and place them in push queues. When youwant to process a task, you must create a new task object and place it on aqueue. You can explicitly specify the service and handler that process the task,and optionally pass task-specific data along to the handler. You can alsofine-tune the configuration for the task, like scheduling a time in the futurewhen it should be executed or limiting the number of times you want the task tobe retried if it fails.

Creating a new task

Specifying the worker service

When a task is popped off its queue, the Task Queue service sends it onto a worker service. Every task has atarget and aurl, which determinewhat service and handler will ultimately perform the task.

target

The target specifies the service that will receive the HTTP request to perform the task. It is a string that specifies a service/version/instance in any one of thecanonical forms. The most often-used forms are:

    service    version.service    instance.version.service

The target string is prepended to the domain name of your app. There are threeways to set the target for a task:

• Declare the target when you construct the task.

• Include atarget directive when you define a queue in thequeue.yaml, as in thedefinition ofqueue-blue. All tasks added to a queue with atarget will use that target, even if a different target was assigned to the task at construction time.

• If no target is specified according to either of the previous two methods,then the task's target is the version of the service that enqueues it.Note that if you enqueue a task from the default service and version inthis manner, and the default version changes before the task executes, itwill run in the new default version.

url

Theurl selects one of the handlers in the target service, which willperform the task.

Theurl should match one of the handler URL patterns in the targetservice. Theurl can include query parameters if the method specified in the task isGET orPULL. If nourl is specified the default URL/_ah/queue/[QUEUE_NAME] is used, where[QUEUE_NAME] is the name ofthe task's queue.

Passing data to the handler

You can pass data to the handler as query parameters in the task's URL, butonly if the method specified in the task isGET orPULL.

Naming a task

When you create a new task, App Engine assigns the task a unique name bydefault. However, you can assign your own name to a task by using thenameparameter. An advantage of assigning your own task names is that named tasks arede-duplicated, which means you can use task names toguaranteethat a task is only added once. De-duplication continues for 9 days after thetask is completed or deleted.

Note that de-duplication logic introduces significant performance overhead,resulting in increased latencies and potentially increased error ratesassociated with named tasks. These costs can be magnified significantly if tasknames are sequential, such as with timestamps. So, if you assign your own names,we recommend using a well-distributed prefix for task names, such as a hash ofthe contents.

If you assign your own names to tasks, note that the maximum name length is 500characters, and the name can contain uppercase and lowercase letters, numbersunderscores, and hyphens.

What's next

• Learn how tocreate taskhandlers.