Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Using Push Queues in PHP

In App Engine push queues, a task is a unit of work to be performed by the application.

  1. Using push queues
  2. Push task execution
  3. URL endpoints
  4. Push queues and the development server
  5. Quotas and limits for push queues

Using push queues

A PHP app sets up queues using a configuration file named queue.yaml (see PHP Task Queue Configuration ). If an app does not have a queue.yaml file, it has a queue named default with some default settings.

To enqueue a task, create a PushTask object and call its add() method. You can add to a queue specified in queue.yaml by supplying a queue name argument to add() . Alternatively, calling add() with no arguments will add the task to the default queue.

The following code creates a task that will be sent as a POST request to the /worker handler of the application. The task contains name and action data, and will be processed by the default queue:

use google\appengine\api\taskqueue\PushTask;

$task = new PushTask('/worker.php', ['name' => 'john doe', 'action' => 'send_reminder']);
$task_name = $task->add();

You can also add tasks in bulk to a queue using PushQueue . In the following example, two PushTask objects are added to a PushQueue using the addTasks() method.

use google\appengine\api\taskqueue\PushTask;
use google\appengine\api\taskqueue\PushQueue;

$task1 = new PushTask('/someUrl');
$task2 = new PushTask('/someOtherUrl');
$queue = new PushQueue();
$queue->addTasks([$task1, $task2]);

Push task execution

App Engine executes push tasks by sending HTTP requests to your app. Specifying a programmatic asynchronous callback as an HTTP request is sometimes called a web hook . The web hook model enables efficient parallel processing.

The task's URL determines the handler for the task and the module that runs the handler.

The handler is determined by the path part of the URL (the forward-slash separated string following the hostname), which is specified as the first argument (the url_path ) of the PushTask constructor. The path must be relative and local to your application's root directory.
The module (or frontend or backend) and version in which the handler runs is determined by:

If you do not specify any of these parameters, the task will run in the same module/version in which it was enqueued, subject to these rules:

A task must finish executing and send an HTTP response value between 200–299 within 10 minutes of the original request. This deadline is separate from user requests, which have a 60-second deadline. If the task failed to execute, App Engine retries it based on criteria that you can configure.

Task request headers

Requests from the Task Queue service contain the following HTTP headers:

These headers are set internally by Google App Engine. If your request handler finds any of these headers, it can trust that the request is a Task Queue request. If any of the above headers are present in an external user request to your app, they are stripped. The exception being requests from logged in administrators of the application, who are allowed to set the headers for testing purposes.

Google App Engine issues Task Queue requests from the IP address 0.1.0.2 .

The rate of task execution

You set the maximum processing rate for the entire queue when you configure the queue . App Engine uses a token bucket algorithm to execute tasks once they've been delivered to the queue. Each queue has a token bucket, and each bucket holds a certain number of tokens. Your app consumes a token each time it executes a task. If the bucket runs out of tokens, the system pauses until the bucket has more tokens. The rate at which the bucket is refilled is the limiting factor that determines the rate of the queue. See Defining Push Queues and Processing Rates for more details.

To ensure that the Task Queue system does not overwhelm your application, it may throttle the rate at which requests are sent. This throttled rate is known as the enforced rate . The enforced rate may be decreased when your application returns a 503 HTTP response code, or if there are no instances able to execute a request for an extended period of time. You can view the enforced rate on the Task Queue tab of the Administration Console .

The order of task execution

The order in which tasks are executed depends on several factors:

Task retries

If a push task request handler returns an HTTP status code within the range 200–299, App Engine considers the task to have completed successfully. If the task returns a status code outside of this range, App Engine retries the task until it succeeds. The system backs off gradually to avoid flooding your application with too many requests, but schedules retry attempts for failed tasks to recur at a maximum of once per hour.

You can also configure your own scheme for task retries using the retry_parameters directive in queue.yaml .

When implementing the code for tasks (as worker URLs within your app), it is important to consider whether the task is idempotent . App Engine's Task Queue API is designed to only invoke a given task once; however, it is possible in exceptional circumstances that a task may execute multiple times (such as in the unlikely case of major system failure). Thus, your code must ensure that there are no harmful side-effects of repeated execution.

URL endpoints

Push tasks reference their implementation via URL. For example, a task which fetches and parses an RSS feed might use a worker URL called /app_worker/fetch_feed . You must specify this worker URL when creating a PushTask. In general, you can use any URL as the worker for a task, so long as it is within your application; all task worker URLs must be specified as relative URLs:

use google\appengine\api\taskqueue\PushTask;

(new PushTask('/path/to/my/worker', ['data_for_task' => 1234]))->add();

Securing URLs for tasks

You can prevent users from accessing URLs of tasks by restricting access to administrator accounts. Task queues can access admin-only URLs. You can restrict a URL by adding login: admin to the handler configuration in app.yaml .

An example might look like this in app.yaml :

application: hello-tasks
version: 1
runtime: php
api_version: 1
threadsafe: true

handlers:
- url: /tasks/process
  script: process.php
  login: admin

For more information see PHP Application Configuration: Requiring Login or Administrator Status .

To test a task web hook, sign in as an administrator and visit the URL of the handler in your browser.

Push queues and the development server

When your app is running in the development server, tasks are automatically executed at the appropriate time just as in production.

To disable tasks from running in the development server, run the following command:
dev_appserver.py --disable_task_running

You can examine and manipulate tasks from the developer console at: http://localhost:8000/_ah/admin/taskqueue .

To execute tasks, select the queue by clicking on its name, select the tasks to execute, and click Run Now . To clear a queue without executing any tasks, click Purge Queue .

The development server and the production server behave differently:

Quotas and limits for push queues

Enqueuing a task in a push queue counts toward the following quotas:

The Task Queue Stored Task Bytes quota is configurable in This quota counts towards your Stored Data (billable) quota.

Execution of a task counts toward the following quotas:

The act of executing a task consumes bandwidth-related quotas for the request and response data, just as if the request handler were called by a remote client. When the task queue processes a task, the response data is discarded.

Once a task has been executed or deleted, the storage used by that task is reclaimed. The reclaiming of storage quota for tasks happens at regular intervals, and this may not be reflected in the storage quota immediately after the task is deleted.

For more information on quotas, see Quotas , and the "Quota Details" section of the Admin Console .

The following limits apply to the use of push queues:

Push Queue Limits
Maximum task size 100KB
Maximum number of active queues (not including the default queue) Free apps: 10 queues, Billed apps: 100 queues
Queue execution rate 500 task invocations per second per queue
Maximum countdown/ETA for a task 30 days from the current date and time
Maximum number of tasks that can be added in a batch 100 tasks
Maximum number of tasks that can be added in a transaction 5 tasks

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.