This page describes how to create a
task handler
, the code that handles a push
task. You must provide a request handler to process the task. The mapping from
the request URL to the appropriate handler is declared in your service's
web.xml
, just
like any other request handler. Because you control how to map task requests to
a handler, you're free to organize your task handlers. If your application
processes many different kinds of tasks, you can add all the handlers to a
single 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 an
instance of the worker service specified by the task's target. Task Queue requests are
sent from the IP address
0.1.0.2
.
Your handler does not need to be written in the same language that created and
enqueued the task if the handler is in a
separate service
.
When you write your handler, follow these guidelines:
The code must return an HTTP status code within the range 200?299 to
indicate success. Any other code indicates that the task failed.
Push tasks have a fixed
completion
deadline
that 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 handler
misses the deadline, the Task Queue service assumes the task failed and
will retry it.
When a task's execution time nears the deadline, App Engine raises a
DeadlineExceededException
before the deadline is reached, so you can save your work or log whatever
progress was made.
The handler must be
idempotent
.
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 deliver
it to a handler at least once. Note that in some rare circumstances, multiple task
execution is possible, so your code must ensure that there are no harmful
side-effects of repeated execution.
Task Queue uses the HTTP code in the handler's response to determine if the
task succeeded. The response from the handler is seen only by the Task Queue service
and only to determine if the task succeeded. The queue ignores all other fields
in the response. Then the service discards the response. The originating app
never
receives
any of the data. If a task fails, the Task Queue service retries the
task by sending another request.
User-supplied data can be delivered to the handler in the request as a query string or as a
payload in the request body. Inserting user data is described in
Creating Tasks
. If the request includes data, the handler must know how
it was inserted into the request. The exact code you use to fetch the data from
the 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.
A push task HTTP request has special headers set by App Engine, which contain
task-specific information your handler can use.
If these headers are present in an external user request to your app, they are stripped
and replaced. The sole exception is for requests from logged-in administrators
of the application, who are allowed to set headers for testing purposes. On the other hand, headers
are 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 is
0
. 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 that
the request is a Task Queue request.
In addition, requests from Task Queue can contain the following headers:
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 to
App Engine administrators
. Task requests themselves are
issued by App Engine and can always target a restricted URL.
You can read about restricting URLs at
Security and
Authentication
.
An example you would use in
web.xml
to restrict everything starting with
/tasks/
to admin-only is:
<security-constraint>
<web-resource-collection>
<web-resource-name>tasks</web-resource-name>
<url-pattern>/tasks/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
For more on the format of
web.xml
, see the documentation for the
the deployment descriptor
.
What's next