定期的なスケジュール設定されたイベントの開始条件

3 種類の開始条件を使用すると、自動化を事前にスケジュールできます。

1. Time.ScheduledTimeEvent
2. Time.RecurringClockTimeScheduledEvent
3. Time.RecurringSolarTimeScheduledEvent

最初の Time.ScheduledTimeEvent を使用すると、将来の特定の瞬間に 1 回だけ、または時計の時間や太陽光イベント（日の出または日の入り）に基づいて定期的に自動化を開始するようにスケジュールできます。

たとえば、この開始条件では、毎日午後 10 時に自動化が開始されます。

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(22, 0, 0, 0)))
}

時計の時間の代わりに、太陽光イベントを指定することもできます。このタイプの開始条件の パラメータは、 SolarTimeStruct 次の要素で構成されるです。

1. type、 どちらかが SolarTimeType.Sunrise または SolarTimeType.Sunset。
2. offset: 太陽光イベントを基準とした開始時刻を任意の時間だけずらすことができます。正の値は太陽光イベントの後に遅延を発生させ、 負の値は太陽光イベントの前に開始条件をトリガーします。

次の例は、毎日日の出の 15 分前に自動化を開始する開始条件です。

starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(
    Time.ScheduledTimeEvent.solarTime(
      SolarTimeStruct(SolarTimeType.Sunrise, java.time.Duration.ofMinutes(-15))
    )
  )
}

後の 2 つの開始条件は、定期的なスケジュール イベントの開始条件です。これを使用すると、 時間ベースとカレンダーベースの両方の条件を含む、より具体的な条件に従って定期的に実行される自動化を作成 できます。

Time.RecurringClockTimeScheduledEvent を使用すると、1 つ以上の時間または日付の条件に基づいて自動化をスケジュールできます。 この開始条件では、Unix の cron ユーティリティで使用される構文に似た構文を使用して、定期的な自動化のスケジュールを指定します。

Time.RecurringSolarTimeScheduledEvent を使用すると、日の出または日の入りの時刻に基づいて自動化をスケジュールできます。必要に応じて、カレンダーベースの条件と組み合わせることもできます。

cron 式

cron は、Unix システムと Linux システムで定期的なジョブをスケジュールするために使用されるコマンドです。すでにご存じかもしれません。

定期的なスケジュール イベントの開始条件では、cron で使用される構文に似たスケジューリング式構文が使用されます。そのため、これらの開始条件で使用されるスケジューリング式は cron 式と呼ばれます。

cron にはいくつかの種類があり、実装によって構文が異なります。定期的なスケジュール イベントの開始条件の cron 式では、Quartz スケジューラと同じ構文が使用されます。 Quartz の cron 式構文については、Quartz の ドキュメントCronExpressionをご覧ください。

例

いくつか例を挙げて説明します。

ユースケース	秒	分	時間	日	月	曜日	年
24 時間ごとに深夜に実行	0	0	0	?	*	*	*
毎週火曜日の午前 6 時 00 分に実行	0	30	19	?	*	3	*
2 月の毎時 15 分に実行	0	15	*	?	2	*	*
1 時間に 1 回実行	0	0	*	?	*	*	*
1 月から 3 月まで、毎月 1 日に最も近い平日の深夜に 24 時間ごとに実行	0	0	0	?	1-3	1W	*
2 月の第 2 木曜日の毎時 15 分に実行	0	15	*	?	2	5#2	*
2 月の月末の毎時 15 分に実行	0	15	*	L	2	?	*
毎週火曜日と木曜日の午前 6 時 00 分に実行	0	30	19	?	*	3,5	*

RecurringClockTimeScheduledEvent

RecurringClockTimeScheduledEvent 開始条件では、cron 式文字列が Time.RecurringClockTimeScheduledEvent.cronExpression フィールドに割り当てられます。

次の例は、4 月の毎週水曜日の午後 8 時 00 分に自動化を開始する RecurringClockTimeScheduledEvent 開始条件です。

starter<_>(structure, event = Time.RecurringClockTimeScheduledEvent) {
  parameter(Time.RecurringClockTimeScheduledEvent.cronExpression("0 0 20 ? 4 4 *"))
}

RecurringSolarTimeScheduleEvent

RecurringSolarTimeScheduleEvent 開始条件は、次の 2 つのパラメータを受け取ります。

1. SolarTimeStruct。
2. cronExpression：日、月、曜日、年のフィールドのみで構成される cron 式のサブセット。太陽光の時刻によって自動化が開始される正確な時刻が決まるため、秒、分、時のフィールドは省略されます。

次の例は、4 月の毎週水曜日の日の出の 1 時間後に自動化を開始する開始条件です。

starter<_>(structure, event = Time.RecurringSolarTimeScheduledEvent) {
  parameter(
    Time.RecurringSolarTimeScheduledEvent.solarTime(
      TimeTrait.SolarTimeStruct(SolarTimeType.Sunrise, Duration.ofHours(1))
    )
  )
  parameter(Time.RecurringSolarTimeScheduledEvent.cronExpression("? 4 4 *"))
}