週期性排定事件啟動條件

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

  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 *
在二月每小時的整點過後的四分之一執行 0 15 * ? 2 * *
每小時執行一次 0 0 * ? * * *
從 1 月到 3 月，每 24 小時在午夜執行，且必須是當月最接近 1 日的平日 0 0 0 ? 1-3 1W *
在二月的第二個星期四，每小時一刻過後一次 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:00 啟動自動化動作：

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 *"))
}