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.yaml ファイルは、Go のソースコードと同じディレクトリに配置する必要があります。 cron.yaml は、Go アプリケーションのスケジュール設定されたタスクを構成します。

YAML 形式について詳しくは YAML ウェブサイトをご覧ください。

cron ジョブの定義

要素 説明
description 省略可。説明は GCP Console と開発サーバーの管理インターフェースに表示されます。この値は引用符で囲んでください。
retry_parameters 省略可。cron ジョブのリクエスト ハンドラが 200 未満または 299 を超える HTTP ステータス コードを返した場合、App Engine はジョブが失敗したものとみなします。デフォルトでは、失敗したジョブは再試行されません。構成ファイルに retry_parameters ブロックを追加すると、失敗したジョブを再試行するようにできます。

詳しくは、cron の再試行をご覧ください。

schedule 必須。cron ジョブの実行スケジュールを定義します。以下の構文を参照してください
target

target 文字列はアプリのホスト名の先頭に追加されます。通常、これはサービスの名前です。cron ジョブは、トラフィックに対して構成されている、指定されたサービスのバージョンにルーティングされます。

target で指定されたサービス名が見つからない場合、cron リクエストは default サービスか、トラフィックを受信するように構成されているアプリのバージョンにルーティングされます。ルーティングに関する詳細については、リクエストのルーティング方法をご覧ください。

ディスパッチ ファイルを使用すると、ジョブが再ルーティングされることがあります。たとえば、次のような cron.yaml および dispatch.yaml ファイルの場合、たとえターゲットが service1 であってもジョブは service2 で実行されます。


# 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
timezone timezone には、zoneinfo タイムゾーンの標準名を指定してください。タイムゾーンを指定しない場合、UTC(GMT)でスケジュールされます。
url 必須。url フィールドには、cron サービスによって呼び出されるアプリケーション内の URL を指定します。詳しくは、cron の URL を保護するをご覧ください。

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 要素を定義するには、間隔のタイプを選択します。

終了時刻の間隔
  • [TYPE]: 毎日実行する間隔には every 接頭辞を含める必要があります。

    例: schedule: every 12 hours

  • [INTERVAL_VALUE]: 整数値とそれに対応する時間の単位。有効な時間の単位は次のとおりです。
    • minutes または mins
    • hours
  • [INTERVAL_SCOPE]: 該当しません。ジョブを実行する特定の開始時刻または時間範囲を設定するには、開始時刻の間隔またはカスタムの間隔の構文をご覧ください。
終了時刻の間隔の例
終了時刻の間隔を使用してジョブのスケジュールを定義する方法を理解する場合は、次の例が役立ちます。
  • 毎日 00:00 に実行を開始し、次回のジョブ実行まで 5 分間待機する。各ジョブが終了すると、cron サービスは 5 分間待機してから次のジョブを実行する。
    schedule: every 5 minutes
  • 毎日 00:00 に実行を開始し、次回のジョブ実行まで 30 分間待機する。各ジョブが終了すると、cron サービスは 30 分間待機してから次のジョブを実行する。
    schedule: every 30 mins
開始時刻の間隔
  • [TYPE]: 毎日実行する間隔には every 接頭辞を含める必要があります。

    例: schedule: every 12 hours

  • [INTERVAL_VALUE]: 整数値とそれに対応する時間の単位。有効な時間の単位は次のとおりです。
    • minutes または mins
    • hours
  • [INTERVAL_SCOPE]: [INTERVAL_VALUE] に対応する句を指定します。カスタム時間範囲を定義するか、24 時間の synchronized オプションを使用できます。
    • ジョブを実行する具体的な開始時刻と時間範囲を定義するには、from [HH:MM] to [HH:MM] 句を含めます。

      時刻の値は 24 時間形式の HH:MM で指定する必要があります:

      • HH00 から 23 までの整数です。
      • MM00 から 59 までの整数です。
    • 24 時間の時間範囲(from 00:00 to 23:59)を指定し、それを [INTERVAL_VALUE] の値で均等に分割する場合は、synchronized を使用します。

      重要: [INTERVAL_VALUE] に指定する値は 24 の約数でなければなりません。そうでないと、エラーが発生します。つまり [INTERVAL_VALUE] の有効な値は、1234681224 です。

開始時刻の間隔の例
開始時刻の間隔を使用してジョブのスケジュールを定義する場合は、以下の例を参考にしてください。
  • 毎日 10:00~14:00 に 5 分間隔で実行する:
    schedule: every 5 minutes from 10:00 to 14:00
  • 毎日 08:00~16:00 に 1 時間ごとに実行する:
    schedule: every 1 hours from 08:00 to 16:00
  • 毎日 00:00 を起点として 2 時間ごとに実行する:
    schedule: every 2 hours synchronized
カスタムの間隔
  • [TYPE]: カスタムの間隔では、every 接頭辞を含めて繰り返しの間隔を定義するか、月の日付のリストを定義できます。
    • 繰り返しの間隔を定義するには、every 接頭辞を使用します。

      例:

      schedule: every day 00:00
      schedule: every monday 09:00

    • 具体的な日付を定義する場合は、序数を使用する必要があります。有効な値は、月の初日からその月の最終日を表す値までです。たとえば、次のようになります。
      • 1st または first
      • 2nd または second
      • 3rd または third
      • 最大 31st または thirtyfirst まで

      例:

      schedule: 1st,3rd tuesday
      schedule: 2nd,third wednesday of month 09:00

  • [INTERVAL_VALUE]: カスタムの間隔には、ジョブを実行する具体的な日付や曜日を含めることができます。リストはカンマ区切りのリストで定義する必要があり、以下のいずれかの値を含めることができます。
    • その月の日付を表す整数値で、最大 31 日まで。たとえば、次のようになります。
      • 1
      • 2
      • 3
      • 最大 31 まで
    • 曜日名を表す次の長い値または省略値の任意の組み合わせ:
      • monday または mon
      • tuesday または tues
      • wednesday または wed
      • thursday または thurs
      • friday または fri
      • saturday または sat
      • sunday または sun
      • すべての曜日を指定するには、day を使用します。

    例:

    schedule: 2nd monday,thurs
    schedule: 1,8,15,22 of month 09:00
    schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00

  • [INTERVAL_SCOPE]: 指定した [INTERVAL_VALUE] に対応する句を指定します。カスタムの間隔には of [MONTH] 句を含め、単一の月または複数の月のカンマ区切りのリストを指定できます。また、ジョブを実行する具体的な時刻も定義する必要があります。たとえば、of [MONTH] [HH:MM] のように定義します。

    of 句を省略した場合、カスタムの間隔はデフォルトで毎月実行されます。

    • [MONTH]: 月をカンマ区切りのリストで指定します。月の名前は、以下の長い名前と短縮形が混在してもかまいません。
      • january または jan
      • february または feb
      • march または mar
      • april または apr
      • may
      • june または jun
      • july または jul
      • august または aug
      • september または sep
      • october または oct
      • november または nov
      • december または dec
      • すべての月を指定するには、month を使用します。
    • [HH:MM]: 時刻の値を 24 時間形式の HH:MM で指定します。
      • HH00 から 23 までの整数です。
      • MM00 から 59 までの整数です。
    • 例:

      schedule: 1st monday of sep,oct,nov 09:00
      schedule: 1 of jan,april,july,oct 00:00

カスタムの間隔の例
カスタムの間隔を使用してジョブのスケジュールを定義する方法を理解する場合は、次の例が役立ちます。
  • 毎日 00:00 に実行する:
    schedule: every day 00:00
  • 毎週月曜日の 09:00 に実行する:
    schedule: every monday 09:00
  • 3 月の第 2 水曜日の 17:00 に 1 回だけ実行する:
    schedule: 2nd wednesday of march 17:00
  • 5 月の最初の 2 週の月曜日、水曜日、金曜日の 10:00 に 1 回ずつ、つまり合計で 6 回実行する:
    schedule: 1st,second mon,wed,fri of may 10:00
  • 1 週間に 1 回実行する。毎月 1 日を起点として 7 日ごとの 09:00 に 1 回実行する:
    schedule: 1,8,15,22 of month 09:00
  • 隔週で実行する。毎月第 1 および第 3 月曜日の 04:00 に 1 回実行する:
    schedule: 1st,third Monday of month 04:00
  • 毎年 3 回実行する。9 月、10 月、11 月の第 1 月曜日の 09:00 に 1 回実行する:
    schedule: 1st monday of sep,oct,nov 09:00
  • 四半期ごとに 1 回実行する。1 月、4 月、7 月、10 月の初日の 00:00 に 1 回実行する:
    schedule: 1 of jan,april,july,oct 00:00

cron の再試行

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

次に cron.yaml ファイルの例を示します。ここでは、1 つの cron ジョブを最大 5 回(デフォルト)まで再試行し、その際にバックオフの間隔を 2.5 秒から始めて、再試行ごとに 2 倍ずつ長くしていきます。

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

cron 再試行構文

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

要素 説明
job_retry_limit 失敗した cron ジョブの再試行回数の最大値(5 回以下)。job_age_limit とともに指定すると、App Engine は両方の上限に達するまで cron ジョブを再試行します。このパラメータを省略すると、上限はデフォルトで 5 回に設定されます。
job_age_limit 失敗した cron ジョブを再試行する制限時間。cron ジョブを最初に実行した時点から計測されます。値は数値の後に時間の単位を付けたものです。単位は、s が秒、m が分、h が時間、d が日を表します。たとえば、5d という値は、cron ジョブの実行を最初に試みてから 5 日間という制限を指定します。job_retry_limit とともに指定すると、App Engine は両方の上限に達するまで cron ジョブを再試行します。
min_backoff_seconds 失敗後 cron ジョブを再試行するまでに待機する最小時間(秒)。
max_backoff_seconds 失敗後 cron ジョブを再試行するまでに待機する最大時間(秒)。
max_doublings 失敗した cron ジョブの再試行間隔が一定になるまでの、間隔が倍増する最大回数。この一定間隔は 2**(max_doublings - 1) * min_backoff となります。

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 個のタスクのスケジュールを設定できます。

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

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

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