タスクハンドラを作成する

このページでは、タスクハンドラ(push タスクを処理するコード)を作成する方法を説明します。App Engine は、タスクを実行するために HTTP リクエストをアプリケーションに送信します。デベロッパーは、タスクのコードを実行するためのリクエスト ハンドラを用意する必要があります。リクエスト URL からコードへのマッピングの宣言は、開発するサービスの app.yaml で、他のリクエスト ハンドラと同様に行われます。タスク リクエストからハンドラへのマッピングはデベロッパーが制御するようになっているため、タスクハンドラの体系はデベロッパーが自由に決めることができます。アプリケーションで処理するタスクの種類が多数の場合に、すべてのハンドラをただ 1 つのサービスに追加することも、ハンドラを複数のサービスに振り分けることもできます。

push タスクのリクエスト ハンドラをプログラミングする

タスクキュー サービスによって HTTP ヘッダーが作成され、タスクのターゲットで指定されているワーカー サービスのインスタンスのいずれかに送信されます。App Engine によって、タスクキュー リクエストが IP アドレス 0.1.0.2 から送信されます。

ハンドラの開発に使用する言語は、タスクを作成してキューに追加するときの言語と同一でなくてもかまいませんが、その場合は独立サービスとしてプログラミングする必要があります。

ハンドラをプログラミングするときは、次のガイドラインに従ってください。

  • そのコードから、成功を示すために 200~299 の範囲内の HTTP ステータス コードを返してください。それ以外のコードは、タスクの失敗を示します。

  • push タスクには、所定の完了期限がありますが、これはそのタスクを実行するサービスのスケーリングのタイプによって決まります。自動スケーリング サービスの場合は、経過時間が 10 分に達する前に完了する必要があります。手動または基本スケーリング サービスの場合は、最大 24 時間まで実行できます。ハンドラが期限までに完了できない場合は、タスクキュー サービスはタスクが異常終了したと見なしてタスクを再試行します。

  • ハンドラがべき等かどうかを考慮することが重要です。App Engine の Task Queue API は「少なくとも 1 回」の処理を提供するように設計されています。つまり、タスクが正常に追加された場合、App Engine はそれを少なくとも 1 回処理します。まれに複数のタスクが実行されることもあるので、反復的な実行で有害な副作用が生じないように注意してください。

タスクキューでは、ハンドラのレスポンスに HTTP コードを使用し、タスクが正常に実行されたかどうかを判断します。レスポンスにあるその他のフィールドは、タスクキューではすべて無視されます。アプリケーションには、何のデータも返送されません。タスクが異常終了した場合は、タスクキュー サービスでタスクを再試行するために別のリクエストが送信されます。

レスポンスを認識するのはタスクキュー サービスのみであり、タスクが正常終了したかどうかを判定するのに使用されます。このサービスによってレスポンスは破棄されるので、アプリではどのデータも認識できません。アプリケーションのデータをレスポンスの中に入れないでください。タスクが異常終了した場合は、タスクキュー サービスがタスクを再試行するために別のリクエストが送信されます。

ユーザーから渡されたデータをリクエストの中に入れて配信することもできます。その場合はクエリ文字列として、またはリクエスト本体のペイロードとして配信します。ユーザーデータを挿入する方法の説明は、タスクを作成するをご覧ください。リクエストの中にデータがある場合は、そのデータがどのようにリクエストに挿入されたかをハンドラが知っている必要があります。データをリクエストから取り出すときに使用される実際のコードは、使用するウェブ フレームワークによって異なります。

タスクハンドラをテストするには、管理者としてログインし、ブラウザでハンドラの URL にアクセスします。

リクエスト ヘッダーの意味

push タスクの HTTP リクエストには特別なヘッダーがあります。ここには、ハンドラが使用する可能性のあるタスク固有の情報が含まれています。

これらのヘッダーは App Engine によって内部的に設定されます。これらのヘッダーがアプリケーションへの外部ユーザー リクエストに含まれている場合、ヘッダーは削除されます。ただしログイン済みのアプリケーション管理者からのリクエストは例外で、テストの目的でヘッダーを設定することが許可されます。アプリが開発サーバーで実行されているとき、ヘッダーは削除されません。

タスクキューからのリクエストには、常に次のヘッダーが含まれます。

ヘッダー 説明
X-AppEngine-QueueName キューの名前(デフォルトの push キューの場合はおそらく「default」)。
X-AppEngine-TaskName タスクの名前。名前が指定されていない場合は、システムが生成した一意の ID。
X-AppEngine-TaskRetryCount このタスクが再試行された回数。最初の試行の場合は、この値は 0 です。この試行回数には、インスタンス数不足が原因でタスクが異常終了したため実行フェーズに到達できなかった試行も含まれています。
X-AppEngine-TaskExecutionCount このタスクがこれまでに実行フェーズ中に異常終了した回数。この回数には、インスタンス数不足が原因の失敗は含まれていません。
X-AppEngine-TaskETA タスクの目標実行時間。1970 年 1 月 1 日からの秒数で表します。

リクエスト ハンドラが上記のヘッダーのいずれかを検出した場合、そのリクエストはタスクキュー リクエストであると判断できます。

さらに、タスクキューからのリクエストには、次のヘッダーを含めることができます。

ヘッダー 説明
X-AppEngine-TaskPreviousResponse 前回の再試行の HTTP レスポンス コード。
X-AppEngine-TaskRetryReason タスクを再試行する理由。
X-AppEngine-FailFast 実行中のタスクを、既存のインスタンスが使用できない場合にすぐ失敗とする。

タスクハンドラの URL をセキュリティで保護する

タスクで実行するオペレーションの機密性が高い場合は(たとえば、データに変更を加える)、そのワーカー URL をセキュリティで保護することをおすすめします。悪意のある外部ユーザーから直接呼び出されることを防止するためです。ユーザーがタスクの URL にアクセスできないようにするには、アクセスを App Engine 管理者のみに制限します。タスク リクエストそのものは App Engine によって発行されるため、制限付きの URL をターゲットとすることができます。

app.yaml ファイルのハンドラ設定に login: admin 要素を追加して URL を制限できます。

例:

runtime: go
api_version: go1

handlers:
- url: /worker/.*
  script: _go_app
  login: admin
- url: /.*
  script: _go_app

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Go の App Engine スタンダード環境