建立工作

本頁說明如何建立工作並加入發送佇列。當您要處理工作時，必須先建立新的工作物件並加入佇列。您可以明確指定用於處理工作的服務和處理常式，然後選擇將工作特定資料傳送給處理常式；也可以微調工作的設定，例如安排未來的執行時間，或限制工作失敗時的重試次數。

建立新工作

如要建立工作並將工作加入佇列，請建立 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 個字元，且名稱可以含有大小寫字母、數字、底線和連字號。

後續步驟