创建任务

本页面介绍如何创建任务并将其放入推送队列。如果您要处理任务，必须创建一个新的任务对象，并将其放到队列中。您可以明确指定用于处理任务的服务和处理程序，并且可以选择将特定于任务的数据传递给处理程序。您还可以微调任务的配置，例如，安排将来执行任务的时间，或者限制失败时希望重试任务的次数。

新建任务

如需创建任务并将其加入队列，请创建 PushTask 对象并调用其 add() 方法。您可以向 add() 提供队列名称参数，从而将任务添加到 queue.yaml 中指定的队列。您也可以在不使用参数的情况下调用 add()，此时，任务会被添加到默认队列。

您还可以使用 PushQueue 将任务批量添加到队列中。以下示例使用 addTasks() 方法将两个 PushTask 对象添加到 PushQueue。

以下代码示例演示了如何添加单个任务：

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

以下代码示例演示了如何一次添加多个任务：

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

使用 PushTask 和 PushQueue 时，请在 PHP 文件的顶部添加以下语句：

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

指定工作器服务

当任务从队列中弹出时，任务队列服务会将该任务发送到工作器服务。每个任务都包含一个目标和一个网址，用于确定最终执行任务的服务和处理程序。

target

目标用于指定将接收 HTTP 请求来执行任务的服务。目标是一个字符串，用于以任意一种规范化格式指定服务/版本/实例。最常用的规范格式有：

    service
    version.service
    instance.version.service

目标字符串将添加到应用的域名前面。

  • 在构造任务时声明目标。 如果构造 PushTask 对象，您可以在创建任务时使用 $options 数组中的标头参数明确设置目标。

    $task = new PushTask(
    '/worker',
    [],
    ['header' => "Host: versionHostname"]);

  • 在 queue.yaml 中定义队列时加入 target 指令，如 queue-blue 的定义所述。添加到具有 target 的队列的所有任务都将使用该目标，即便在构建任务时为任务分配了其他目标也是如此。

  • 如果没有采用前面两种方法中的任何一种指定目标，则任务的目标便是将任务加入队列的服务版本。请注意，如果以这种方式从默认服务和版本中将任务加入队列，而在任务执行之前默认版本发生了更改，则该任务将在新的默认版本中运行。

url

url 用来选择目标服务中的一个处理程序来执行任务。

此 url 应与目标服务中的一种处理程序网址格式相匹配。如果任务中指定的方法是 GET 或 PULL，则 url 可以包含查询参数。如果未指定 url，则会使用默认网址 /_ah/queue/[QUEUE_NAME]，其中 [QUEUE_NAME] 是任务队列的名称。

将数据传递给处理程序

您可以将数据作为任务网址中的查询参数传递给处理程序，前提是任务中指定的方法为 GET 或 PULL。

PushTask 构造函数具有 query_data 的位置参数。该数据通常是键值对构成的字典。如果任务的方法是 POST 或 PUT，则数据会被添加到 HTTP 请求的载荷中。如果方法是 GET，则数据会作为查询参数被添加到网址中。

为任务命名

默认情况下，在您创建新任务时，App Engine 会为该任务分配一个唯一的名称。不过，您可以使用 name 参数自行为任务命名。自行为任务命名的好处是，系统会对命名的任务进行去重处理，这意味着您可以使用任务名称来保证任务只会被添加一次。系统会在任务被完成或删除后的 9 天之内继续进行去重处理。

请注意，去重逻辑会产生很大的性能开销，从而导致延迟时间增加，并可能导致与命名任务相关的错误率增加。如果任务名称是按顺序排列的（例如使用时间戳），则这些开销可能会明显增加。因此，如果您自行命名任务，我们建议您为任务名称使用分布合理的前缀，例如内容的哈希值。

如果您自行为任务命名，那么请注意，名称长度不能超过 500 个字符，名称可以包含大写和小写字母、数字、下划线和连字符。

后续步骤