週期性排定事件啟動條件

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

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

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

舉例來說，這個啟動條件會在每天晚上 10:00 啟動自動化動作：

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:00 執行	0	30	19	?	*	3	*
在 2 月期間，每小時的 15 分執行	0	15	*	?	2	*	*
每小時執行一次	0	0	*	?	*	*	*
1 月到 3 月，每 24 小時執行一次，時間為午夜，日期為最接近每月 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. SolarTimeStruct。
2. cronExpression：cron 運算式的子集，僅包含 Day-of-Month、Month、Day-of-Week 和 Year 欄位。太陽時間會決定自動化動作啟動的確切時間，因此會省略「秒」、「分」和「時」欄位。

以下範例是啟動條件，會在 4 月的每週三日出後一小時啟動自動化動作：

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