This page describes how to create tasks and place them in push queues. When you want to process a task, you must create a new task object and place it on a queue. You can explicitly specify the service and handler that process the task, and optionally pass task-specific data along to the handler. You can also fine-tune the configuration for the task, like scheduling a time in the future when it should be executed or limiting the number of times you want the task to be retried if it fails.
Creating a new task
To create and 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() with no arguments will add the task to the default queue.
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
The following code sample shows how to add a single task:
$task = new PushTask( '/worker', ['name' => 'john doe', 'action' => 'send_reminder']); $task_name = $task->add();
The following code sample shows how to add multiple tasks at once:
$task1 = new PushTask('/someUrl'); $task2 = new PushTask('/someOtherUrl'); $queue = new PushQueue(); $queue->addTasks([$task1, $task2]);
When you use
PushQueue, include these statements at the top of
your PHP file:
use google\appengine\api\taskqueue\PushTask; use google\appengine\api\taskqueue\PushQueue;
Specifying the worker service
When a task is popped off its queue, the Task Queue service sends it on to a worker service. Every task has a target and a url, which determine what service and handler will ultimately perform the task.
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 the canonical 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 three ways to set the target for a task:
Declare the target when you construct the task. You can set the target explicitly when creating the task by using the header parameter in the
$optionsarray when you construct the PushTask object:
$task = new PushTask( '/worker', , ['header' => "Host: versionHostname"]);
targetdirective when you define a queue in the
queue.yaml, as in the definition of
queue-blue. All tasks added to a queue with a
targetwill 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 in this manner, and the default version changes before the task executes, it will run in the new default version.
url selects one of the handlers in the target service, which will
perform the task.
url should match one of the handler URL patterns in the target
url can include query parameters if the method specified in the task is
PULL. If no
url is specified the default URL
/_ah/queue/[QUEUE_NAME] is used, where
[QUEUE_NAME] is the name of
the task's queue.
Passing data to the handler
You can pass data to the handler as query parameters in the task's URL, but
only if the method specified in the task is
PushTask constructor has a positional argument for query_data.
The data is usually a dictionary of key-value pairs. If the task's method is
PUT, the data is added to the payload of the HTTP request. If the
method is GET it is added to the URL as query parameters.
Naming a task
When you create a new task, App Engine assigns the task a unique name by
default. However, you can assign your own name to a task by using the
parameter. An advantage of assigning your own task names is that named tasks are
de-duplicated, which means you can use task names to
that a task is only added once. De-duplication continues for 9 days after the
task is completed or deleted.
Note that de-duplication logic introduces significant performance overhead, resulting in increased latencies and potentially increased error rates associated with named tasks. These costs can be magnified significantly if task names 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 of the contents.
If you assign your own names to tasks, note that the maximum name length is 500 characters, and the name can contain uppercase and lowercase letters, numbers underscores, and hyphens.
- Learn how to create task handlers.