This page describes how to create atask handler, the code that handles a pushtask. You must provide a request handler to process the task. The mapping fromthe request URL to the appropriate handler is declared in your service'sapp.yaml, justlike any other request handler. Because you control how to map task requests toa handler, you're free to organize your task handlers. If your applicationprocesses many different kinds of tasks, you can add all the handlers to asingle service, or you can distribute them among multiple services.

Writing a push task request handler

In the queue, the Task Queue service creates an HTTP header and sends it to aninstance of the worker service specified by the task's target. Task Queue requests aresent from the IP address0.1.0.2.

Your handler does not need to be written in the same language that created andenqueued the task if the handler is in aseparate service.

When you write your handler, follow these guidelines:

• The code must return an HTTP status code within the range 200–299 toindicate success. Any other code indicates that the task failed.

  Note: App Engine itself returns a503 status code when instances areoverloaded or otherwise unavailable. The Task Queue service responds to thisby slowing delivery from queues to handlers, to avoid making the problemworse. If you wish to trigger a retry intentionally, use any status codeother than2xx or503.

• Push tasks have a fixedcompletiondeadlinethat depends on the scaling type of the service that's running them.Automatic scaling services must finish before 10 minutes have elapsed.Manual and basic scaling services can run up to 24 hours. If your handlermisses the deadline, the Task Queue service assumes the task failed andwill retry it.

• The handler must beidempotent.App Engine's Task Queue API is designed to provide "at least once"delivery; that is, if a task is successfully added, App Engine will deliverit to a handler at least once. Note that in some rare circumstances, multiple taskexecution is possible, so your code must ensure that there are no harmfulside-effects of repeated execution.

Task Queue uses the HTTP code in the handler's response to determine if thetask succeeded. The response from the handler is seen only by the Task Queue serviceand only to determine if the task succeeded. The queue ignores all other fieldsin the response. Then the service discards the response. The originating appneverreceives any of the data. If a task fails, the Task Queue service retries thetask by sending another request.

User-supplied data can be delivered to the handler in the request as a query string or as apayload in the request body. Inserting user data is described inCreating Tasks. If the request includes data, the handler must know howit was inserted into the request. The exact code you use to fetch the data fromthe request depends on the particular web framework you're using.

To test a task handler, sign in as an administrator and visit the handler's URL in your browser.

Reading request headers

A push task HTTP request has special headers set by App Engine, which containtask-specific information your handler can use.

If these headers are present in an external user request to your app, they are strippedand replaced. The sole exception is for requests from logged-in administratorsof the application, who are allowed to set headers for testing purposes. On the other hand, headersare not removed when your app is running in the development server.

Requests from Task Queue will always contain the following headers:

Header	Description
X-Appengine-QueueName	The name of the queue (possibly "default" for the default push queue).
X-Appengine-TaskName	The name of the task, or a system-generated unique ID if no name was specified.
X-Appengine-TaskRetryCount	The number of times this task has been retried. For the first attempt, this value is0. This number includes attempts where the task failed due to a lack of available instances and never reached the execution phase.
X-Appengine-TaskExecutionCount	The number of times this task has previously failed during the execution phase. This number does not include failures due to a lack of available instances.
X-Appengine-TaskETA	The target execution time of the task, specified in seconds since January 1st 1970.

If your request handler finds any of the headers listed above, it can trust thatthe request is a Task Queue request.

In addition, requests from Task Queue can contain the following headers:

Header	Description
X-Appengine-TaskPreviousResponse	The HTTP response code from the previous retry.
X-Appengine-TaskRetryReason	The reason for retrying the task.
X-Appengine-FailFast	Indicates that a task runningfails immediately if an existing instance is not available.

Securing task handler URLs

If a task performs sensitive operations (such as modifying data), you might want to secure the handler URL to prevent a malicious external user from calling it directly. You can prevent users from accessing task URLs by restricting access toApp Engine administrators. Task requests themselves areissued by App Engine and can always target a restricted URL.

Note: While tasks can use URL paths restricted withlogin: admin, theycannot use URL paths restricted withlogin: required becausetasks are not run as any user. Theadmin restriction is satisfied by theinclusion of theX-Appengine-QueueName header described inReading request headers.

What's next

• Learn how todelete tasks.