週期性排定事件啟動條件

你可以透過三種不同的啟動條件，預先排定自動化動作：

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

第一個是 Time.ScheduledTimeEvent， 可讓你根據時鐘時間或太陽事件 (即日出或日落)，排定自動化動作在未來某個精確時間點啟動，或定期啟動。

舉例來說，這項啟動條件會每天晚上 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))
    )
  )
}

後兩項啟動條件是週期性排定事件啟動條件，可讓您根據更具體的條件建立自動化動作，並定期執行，這些條件可包含時間和日曆條件。

Time.RecurringClockTimeScheduledEvent 你可以根據一或多個時間或日期條件，排定自動化巨集。 這個入門範本使用的語法與 Unix cron 公用程式的語法類似，可指定重複自動化動作的排程。

Time.RecurringSolarTimeScheduledEvent 可讓你根據日出或日落時間排定自動化動作， 也可以選擇搭配日曆條件。

cron 運算式

您可能已經熟悉 cron，這是 Unix 和 Linux 系統上用於排定週期性工作的指令。

週期性排定事件啟動器使用的排定運算式語法，與 cron 使用的語法類似，因此與這些啟動器搭配使用的排定運算式稱為 cron 運算式。

cron 有多種「風味」，且這些實作項目之間存在多種語法變化。週期性排定事件啟動器 cron 運算式使用的語法與 Quartz 排程器相同。如要瞭解 Quartz cron 運算式語法，請參閱 Quartz 說明文件CronExpression。

範例

以下列舉幾個例子。

用途	秒	分鐘	小時	當月第幾日	月	星期幾	年
每 24 小時執行一次，時間為午夜	0	0	0	?	*	*	*
每週二上午 6 點執行	0	30	19	?	*	3	*
在 2 月期間，每小時的 15 分執行一次	0	15	*	?	2	*	*
每小時執行一次	0	0	*	?	*	*	*
每年 1 月到 3 月，在最接近每月 1 號的平日午夜執行	0	0	0	?	1-3	1W	*
2 月第二個星期四，每小時的 15 分	0	15	*	?	2	5#2	*
在 2 月的最後一天，每小時的 15 分執行一次	0	15	*	L	2	?	*
每週二和週四早上 6 點執行	0	30	19	?	*	3,5	*

RecurringClockTimeScheduledEvent

在 RecurringClockTimeScheduledEvent 啟動器中，cron 運算式字串會指派給 Time.RecurringClockTimeScheduledEvent.cronExpression 欄位。

以下是RecurringClockTimeScheduledEvent啟動器的範例，可於 4 月每週三晚上 8 點啟動自動化動作：

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

RecurringSolarTimeScheduleEvent

RecurringSolarTimeScheduleEvent 啟動器會採用兩個參數：

1. A SolarTimeStruct。
2. cronExpression：cron 運算式的子集，僅包含「月份中的日期」、「月份」、「星期幾」和「年份」欄位。自動化動作的確切啟動時間取決於太陽時，因此系統會省略「秒」、「分」和「時」欄位。

以下範例是啟動條件，可讓自動化動作在 4 月的每個星期三，於日出後一小時啟動：

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