Déclencheurs d'événements programmés récurrents

Trois déclencheurs différents vous permettent de programmer une automatisation à l'avance :

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

Le premier, Time.ScheduledTimeEvent, vous permet de programmer une automatisation pour qu'elle démarre à un instant précis dans le futur ou de manière récurrente, en fonction de l'heure ou d'un événement solaire (c'est-à-dire le lever ou le coucher du soleil).

Par exemple, ce déclencheur démarre l'automatisation à 22h tous les jours :

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

Vous pouvez également spécifier un événement d'heure solaire au lieu d'une heure. Le paramètre de ce type de starter est un SolarTimeStruct qui se compose des éléments suivants :

1. type, qui est SolarTimeType.Sunrise ou SolarTimeType.Sunset.
2. offset, qui vous permet de décaler l'heure de début par rapport à l'événement solaire de n'importe quelle durée. Les valeurs positives introduisent un délai après l'événement solaire, tandis que les valeurs négatives déclenchent le démarreur avant l'événement solaire.

L'exemple suivant est un déclencheur qui lance l'automatisation 15 minutes avant le lever du soleil chaque jour :

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

Les deux derniers déclencheurs sont des déclencheurs d'événements programmés récurrents. Ils vous permettent de créer des automatisations qui s'exécutent périodiquement selon des critères plus spécifiques, qui peuvent inclure des conditions basées sur le temps et sur le calendrier.

Time.RecurringClockTimeScheduledEvent vous permet de planifier une automatisation en fonction d'une ou de plusieurs conditions de date ou d'heure. Ce starter utilise une syntaxe semblable à celle utilisée par l'utilitaire Unix cron pour spécifier la programmation d'une automatisation récurrente.

Time.RecurringSolarTimeScheduledEvent vous permet de programmer une automatisation en fonction de l'heure du lever ou du coucher du soleil, éventuellement en combinaison avec une condition basée sur le calendrier.

cron expressions

Vous connaissez peut-être déjà cron, une commande utilisée sur les systèmes Unix et Linux pour planifier des tâches récurrentes.

Les déclencheurs d'événements planifiés récurrents utilisent une syntaxe d'expression de planification semblable à celle utilisée par cron. C'est pourquoi les expressions de planification utilisées avec ces déclencheurs sont appelées expressions cron.

Il existe plusieurs "saveurs" de cron et plusieurs variantes de syntaxe dans ces implémentations. Les expressions de déclencheur d'événement planifié récurrent cron utilisent la même syntaxe que le planificateur Quartz. La syntaxe des expressions Quartz cron est expliquée dans la documentation de Quartz sur CronExpression.

Exemples

Voici quelques exemples pour illustrer ce problème.

RecurringClockTimeScheduledEvent

Dans un starter RecurringClockTimeScheduledEvent, la chaîne d'expression cron est attribuée au champ Time.RecurringClockTimeScheduledEvent.cronExpression.

Voici un exemple de déclencheur RecurringClockTimeScheduledEvent qui lance l'automatisation à 20h00, tous les mercredis du mois d'avril :

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

RecurringSolarTimeScheduleEvent

Le starter RecurringSolarTimeScheduleEvent prend deux paramètres :

1. Un SolarTimeStruct.
2. cronExpression : sous-ensemble d'une expression cron ne contenant que les champs "Jour du mois", "Mois", "Jour de la semaine" et "Année". L'heure solaire détermine l'heure exacte à laquelle l'automatisation commencera. Les champs "Seconde", "Minute" et "Heure" sont donc omis.

L'exemple suivant est un déclencheur qui lance une automatisation une heure après le lever du soleil, tous les mercredis du mois d'avril :

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