cron.yaml リファレンス

アプリケーションのスケジュール設定されたタスクを定義するには、cron.yaml ファイルを使用します。

cron ジョブをテスト、デプロイ、削除する方法など、その他のスケジュール設定タスクの詳細については、cron を使用してタスクのスケジュールを設定するをご覧ください。

例

cron.yaml ファイルの例を次に示します。

cron:
- description: "daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
- description: "monday morning mailout"
  url: /mail/weekly
  schedule: every monday 09:00
  timezone: Australia/NSW
- description: "new daily summary job"
  url: /tasks/summary
  schedule: every 24 hours
  target: beta

構文

cron ジョブの定義

# cron.yaml
cron:
- description: "test dispatch vs target"
  url: /tasks/hello_service2
  schedule: every 1 mins
  target: service1

# dispatch.yaml:
dispatch:
- url: '*/tasks/hello_service2'
  service: service2

cron ジョブの schedule を定義する

cron ジョブは繰り返しの間隔に基づいてスケジュール設定し、簡単な英語のような形式を使用して指定します。ジョブは 1 日に複数回実行するようにスケジュール設定することも、具体的な月と日付に実行するようにスケジュール設定することもできます。

1 日未満の間隔

繰り返しのスケジュールに基づき、ジョブを 1 日に複数回実行するには、1 日未満の間隔を使用します。定義できるのは、終了時刻の間隔または開始時刻の間隔のいずれかです。

• 終了時刻の間隔: ジョブの「終了時刻」から次のジョブが開始されるまでの時間を定義します。「終了時刻」とは、ジョブが完了した時刻またはタイムアウトした時刻のことです。Cron サービスは、00:00 に開始して 24 時間を通して、このタイプの間隔でジョブを実行し、各ジョブの間は指定された時間だけ待機します。

  例: every 5 minutes というスケジュールの場合、ジョブは毎日 5 分間隔で実行されます。たとえば、このスケジュールに従って実行されているジョブが 02:01 に完了した場合、次回のジョブの実行まで 5 分間待機し、02:06 に再度開始されることになります。

• 開始時刻の間隔: cron サービスが各ジョブを開始するための一定の時間間隔を定義します。終了時刻の間隔とは異なり、開始時刻の間隔では、前のジョブが完了またはタイムアウトした時期に関係なく各ジョブが実行されます。ジョブを実行する時刻は、一定の時刻範囲として設定できます。また、00:00 を起点として 1 日 24 時間実行するように設定することもできます。

  ジョブの開始時刻が厳密に決められているため、ジョブのインスタンスの実行時間が定義されている時間間隔よりも長かった場合、cron サービスはジョブをスキップする場合があります。つまり、前のジョブが完了またはタイムアウトしていない場合、設定された時刻範囲内の個別の開始時刻がスキップされる場合があることになります。

  例: every 5 minutes from 10:00 to 14:00 というスケジュールの場合、最初のジョブの実行は 10:00 に開始され、以後 5 分おきにジョブが実行されます。ただし、最初のジョブの実行に 7 分かかった場合、10:05 のジョブはスキップされることになるため、cron サービスは 10:10 までこのジョブの別のインスタンスを実行しません。

カスタムの間隔

スケジュールは、カスタムの間隔を使用して定義できます。この場合、1 日または数日に 1 回、あるいは 1 か月または数か月に 1 回の間隔を選択してジョブを実行できます。カスタムのスケジュールに従って実行されるジョブは、年間を通じて選択した日および月の特定の時刻にのみ実行されます。

例: 1,2,3 of month 07:00 というスケジュールの場合、各月の 1～3 日の 07:00 に 1 回だけジョブが実行されます。

schedule に関する重要な考慮事項:

• 設定する間隔は、1 日未満の間隔またはカスタムの間隔のいずれかに決める必要があります。別のタイプの間隔から要素を組み合わせて使用することはできません。たとえば、schedule: every 6 hours mon,wed,fri というスケジュールの定義は無効です。
• 任意のある時点で実行するジョブのインスタンスは 1 つのみにする必要があります。cron サービスは、「少なくとも 1 回」の処理を提供するように設計されています。つまり、ジョブがスケジュール設定されている場合、App Engine はそのジョブ リクエストを少なくとも 1 回送信します。まれに、同じジョブの複数のインスタンスがリクエストされる場合があるため、リクエスト ハンドラはべき等である必要があります。また、そのような状況が発生した場合でも有害な副作用がないようにコードを記述する必要があります。

schedule の書式

ジョブが実行される時期を指定するには、以下の構文を使用して schedule 要素を定義します。

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

schedule 要素を定義するには、間隔のタイプを選択します。

cron の再試行

cron ジョブのリクエスト ハンドラが 200 未満または 299 を超えるステータス コードを返した場合、App Engine はジョブが失敗したものとみなします。デフォルトでは、失敗したジョブは再試行されません。構成ファイルに retry_parameters ブロックを追加すると、失敗したジョブを再試行できます。

cron:
- description: "retry demo"
  url: /retry
  schedule: every 10 mins
  retry_parameters:
    min_backoff_seconds: 2.5
    max_doublings: 5

cron 再試行構文

下の表で再試行パラメータを説明します。

cron リクエスト

リクエスト ヘッダー

cron サービスからのリクエストには次の HTTP ヘッダーが含まれます。

X-Appengine-Cron: true

この X-Appengine-Cron ヘッダーは Google App Engine 内部で設定されます。リクエスト ハンドラでこのヘッダーを検出した場合は、リクエストが cron リクエストであると判断できます。このヘッダーが、外部ユーザーからアプリケーションへのリクエストに指定されていた場合は、削除されます。アプリケーションの管理者がログインしてリクエストした場合は例外で、テストするために、このヘッダーを設定することができます。

発行元の IP アドレス

Google App Engine は cron リクエストを IP アドレス 0.1.0.1 から発行します。

期限

cron のタイムアウト期限は、アプリに設定されているインスタンス クラスとスケーリング タイプによって異なります。

自動スケーリング

約 10 分でタイムアウトします。

基本スケーリング、手動スケーリング

24 時間以内にタイムアウトします。

詳しくは、スケーリング タイプとインスタンス クラスをご覧ください。

制限

無料アプリケーションの場合、最大 20 個のタスクのスケジュールを設定できます。有料アプリケーションの場合、最大 250 個のタスクのスケジュールを設定できます。