注: PHP 5 は、2024 年 1 月 30 日にサポートが終了しました。既存の PHP 5 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの PHP に移行することをおすすめします。

タスクの作成

このページでは、タスクを作成して push キューに配置する方法を説明します。タスクを処理する場合は、新しいタスクオブジェクトを作成してキューに配置する必要があります。タスクを処理するサービスとハンドラを明示的に指定し、必要に応じてタスク固有のデータをハンドラに渡すこともできます。また、タスクを実行するタイミングのスケジューリング、タスクが失敗した場合の再試行回数の制限など、タスクの構成を微調整することもできます。

新しいタスクを作成する

タスクを作成してエンキューするには、PushTaskオブジェクトを作成して、add() メソッドを呼び出します。add() にキュー名の引数を指定すると、queue.yaml で指定されたキューに追加できます。または、引数なしで add() を呼び出すと、タスクがデフォルトキューに追加されます。

PushQueue を使用して複数のタスクを一括で追加することもできます。次の例では、addTasks() メソッドを使用して、2 つの 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;

ワーカーサービスを指定する

タスクがキューから取り出される（ポップ）と、タスクはタスクキューサービスによってワーカーサービスに送信されます。いずれのタスクにもターゲットと url があり、どのサービスとハンドラがそのタスクを実行するかがこれらによって決まります。

`target`

ターゲットは、どのサービスがタスク実行の HTTP リクエストを受け取るかを指定します。これは文字列であり、サービス / バージョン / インスタンスを正規形式のいずれかで指定します。よく使用される形式は次のとおりです。

    service
    version.service
    instance.version.service

ターゲット文字列の前には、アプリのドメイン名が付加されます。タスクのターゲットを設定するには、次の 3 つの方法があります。

タスクを作成するときにターゲットを宣言します。タスクの作成時にターゲットを明示的に設定するには、PushTask オブジェクトを作成するときに、$options 配列内で header パラメータを使用します。
```
$task = new PushTask(
    '/worker',
    [],
    ['header' => "Host: versionHostname"]);
```
queue.yaml でキューを定義するときに、target ディレクティブを指定します（queue-blue の定義をご覧ください）。target が指定されているキューに追加されるタスクはすべて、そのターゲットを使用します。タスクの作成時に別のターゲットが割り当てられていても無視されます。
上記の 2 つの方法のいずれかでターゲットが指定されていない場合、タスクをキューに追加したサービスのバージョンが、そのタスクのターゲットになります。この方法でタスクをデフォルトのサービスとバージョンからキューに追加した場合、タスクの実行前にデフォルトのバージョンが変更されると、タスクは変更後のデフォルトのバージョンで実行されます。

`url`

url に基づいて、ターゲットサービスのハンドラのうち 1 つが選択され、そのハンドラによってタスクが実行されます。

url は、ターゲットサービス内のハンドラ URL パターンのうち 1 つに一致する必要があります。タスクに指定されたメソッドが GET または PULL である場合は、url にクエリパラメータを含めることができます。url が指定されていない場合は、デフォルトの URL /_ah/queue/[QUEUE_NAME] が使用されます。ここで [QUEUE_NAME] はタスクのキューの名前です。

データをハンドラに渡す

データをハンドラに渡す場合、タスクの URL 内のクエリパラメータとして渡す方法がありますが、この方法が可能なのはタスクで指定されているメソッドが GET か PULL の場合のみです。

PushTask コンストラクタには query_data の位置引数が含まれています。データは通常、Key-Value ペアの辞書です。タスクのメソッドが POST または PUT の場合、データは HTTP リクエストのペイロードに追加されます。メソッドが GET の場合は、クエリパラメータとして URL に追加されます。

タスクに名前を付ける

新しいタスクを作成すると、デフォルトではタスクに一意の名前が割り当てられます。ただし、name パラメータを使用すると、タスクに独自の名前を割り当てることができます。独自のタスク名を割り当てることの利点は、名前付きのタスクでは重複が除外されることです。つまり、タスク名を使用すると、タスクが 1 回のみ追加されることを保証できます。重複の除外は、タスクが完了するか、削除されてから 9 日間続きます。

重複除外ロジックはパフォーマンスのオーバーヘッドを大幅に増加させるため、レイテンシが増加し、場合によっては名前付きタスクに伴うエラー率が高まるので注意してください。このようなコストは、タイムスタンプのように連続したタスク名が付けられている場合、大幅に増大する可能性があります。そのため、独自の名前を割り当てる場合は、コンテンツのハッシュなどの適度に分散された接頭辞をタスク名に使用することをおすすめします。

独自のタスク名を割り当てる場合は 500 文字以内にする必要があります。また、タスク名には英字の大文字と小文字、数字、アンダースコア、ハイフンを使用できます。

次のステップ

タスクハンドラを作成する方法を学習する。