App Engine SDK ベースのツール用の cron.xml リファレンス

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<cronentries>
  <cron>
    <url>/recache</url>
    <description>Repopulate the cache every 2 minutes</description>
    <schedule>every 2 minutes</schedule>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
  </cron>
  <cron>
    <url>/weeklyreport</url>
    <description>Mail out a weekly report</description>
    <schedule>every monday 08:30</schedule>
    <timezone>America/New_York</timezone>
    <target>version-2</target>
  </cron>
</cronentries>

このフォーマットを記述する XSD については、SDK のファイル docs/cron.xsd をご覧ください。

構文

cron.xml ファイルは、アプリケーションの WEB-INF ディレクトリに appengine-web.xml とともに置く必要があります。cron.xml では、Java アプリケーションのスケジュールされたタスクが構成されます。

cron ジョブの定義

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

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

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

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

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

<timezone> timezone には、標準的な zoneinfo タイムゾーンの名前を指定してください。タイムゾーンを指定しない場合、ジョブは UTC(GMT)で実行されます。
<url> 必須。<url> フィールドには、アプリケーション内の URL を指定します。この <url> 要素に XML 特殊文字(&<>'")を使用する場合は、その文字をエスケープする必要があります。

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</schedule> は無効なスケジュール定義の例です。
  • ある時点で実行するジョブのインスタンスは 1 つのみにする必要があります。cron サービスは、「少なくとも 1 回」の処理を提供するように設計されています。つまり、ジョブがスケジュール設定されている場合、App Engine はそのジョブ リクエストを少なくとも 1 回送信します。まれに、同じジョブの複数のインスタンスがリクエストされる場合があるため、リクエスト ハンドラはべき等である必要があります。また、そのような状況が発生した場合でも有害な副作用がないようにコードを記述する必要があります。

schedule の書式

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

<schedule>[TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]</schedule>

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

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

    例: <schedule>every 12 hours</schedule>

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

    例: <schedule>every 12 hours</schedule>

  • [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</schedule>
  • 毎日 08:00~16:00 に 1 時間ごとに実行する:
    <schedule>every 1 hours from 08:00 to 16:00</schedule>
  • 毎日 00:00 を起点として 2 時間ごとに実行する:
    <schedule>every 2 hours synchronized</schedule>
カスタムの間隔
  • [TYPE]: カスタムの間隔では、every 接頭辞を含めて繰り返しの間隔を定義するか、月の日付のリストを定義できます。
    • 繰り返しの間隔を定義する場合は、every 接頭辞を使用できます。

      例:

      <schedule>every day 00:00</schedule>
      <schedule>every monday 09:00</schedule>

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

      例:

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

  • [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>
    <schedule>1,8,15,22 of month 09:00</schedule>
    <schedule>1st mon,wednesday,thu of sep,oct,nov 17:00</schedule>

  • [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>
      <schedule>1 of jan,april,july,oct 00:00</schedule>

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

cron の再試行

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

次に示す cron.xml ファイルのサンプルでは、1 つの cron ジョブが 5 回(デフォルト値)まで再試行を繰り返します。再試行間隔は 2.5 秒から始まり、試行ごとに 2 倍になります。

<cronentries>
  <cron>
    <url>/retry</url>
    <description>Retry on jsdk</description>
    <schedule>every 10 minutes</schedule>
    <retry-parameters>
      <min-backoff-seconds>2.5</min-backoff-seconds>
      <max-doublings>5</max-doublings>
    </retry-parameters>
  </cron>
</cronentries>

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

開発サーバーにおける cron のサポート

開発サーバーでは、cron ジョブは自動的には実行されません。ローカル デスクトップの cron やスケジュール設定されたタスクのインターフェースを使用すると、curl や同様のツールでジョブの URL をトリガーできます。

cron ジョブのデプロイ

appcfg.sh ツールを使用して、cron ジョブを App Engine にデプロイできます。

オプション 1: アプリケーション全体をアップロードする

アプリケーション全体をアップロードすると、cron.xml ファイルのエントリにより Cron サービスが更新されます。この処理を行うには、次のコマンドを実行します。

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]
オプション 2: cron の更新分のみをアップロードする

cron の構成だけを更新し、アプリケーションの残りの部分はアップロードしない場合には、次のコマンドを実行します。

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

すべての cron ジョブを削除する

すべての cron ジョブを削除する手順は次のとおりです。

  1. cron.xml ファイルの内容を次のように編集します。

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    

  2. cron.xml ファイルを App Engine にデプロイします。

GCP Console での cron のサポート

GCP Console の [タスクキュー] ページには、cron ジョブを実行しているタスクを表示するタブがあります。

また、[ログ] ページでは、cron ジョブがいつ追加または削除されたかを確認できます。

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

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

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