APScheduler的触发器详解

写作原因

工作需要，特此记录

调度模式

1. DateTrigger：在特定时间点触发任务。
2. IntervalTrigger：按照固定的时间间隔重复执行任务。
3. CronTrigger：按照类 Unix-cron 的表达式调度任务，适用于复杂的时间规则。
4. CalendarIntervalTrigger：基于日历间隔调度任务（官方文档没有）。

DateTrigger

DateTrigger 用于在特定时间点执行任务。它适用于仅需要执行一次的任务。 

from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.triggers.date import DateTrigger
from datetime import datetime

scheduler = BackgroundScheduler()
trigger = DateTrigger(run_date=datetime(2024, 7, 1, 12, 0, 0))
scheduler.add_job(my_job, trigger)
scheduler.start()

 由于仅执行一次任务，所以使用很简单，这里说下run_date参数

使用 datetime 对象：

run_date = datetime(2024, 7, 1, 12, 0, 0) 
trigger = DateTrigger(run_date=run_date) 
scheduler.add_job(my_job, trigger)

 使用字符串

run_date = '2024-07-01 12:00:00'
trigger = DateTrigger(run_date=run_date)
scheduler.add_job(my_job, trigger)

使用 UNIX 时间戳

run_date = 1719844800  # 对应于2024-07-01 12:00:00 UTC
trigger = DateTrigger(run_date=run_date)
scheduler.add_job(my_job, trigger)

IntervalTrigger

IntervalTrigger 用于按照固定的时间间隔重复执行任务。 

时间间隔参数

• weeks: 间隔的周数
• days: 间隔的天数
• hours: 间隔的小时数
• minutes: 间隔的分钟数
• seconds: 间隔的秒数
• start_date: 开始运行任务的时间
• end_date: 停止运行任务的时间
• timezone: 使用的时区

 示例

每隔5分钟运行一次任务

trigger = IntervalTrigger(minutes=5)
scheduler.add_job(my_job, trigger)

 每天中午12点执行任务

from datetime import datetime, time

trigger = IntervalTrigger(days=1, start_date=datetime.combine(datetime.now(), time(12, 0)))
scheduler.add_job(my_job, trigger)

每周一和周四的上午9点执行任务

from datetime import datetime, time

trigger = IntervalTrigger(weeks=1, start_date=datetime.combine(datetime.now(), time(9, 0)))
scheduler.add_job(my_job, trigger, days_of_week='mon,thu')

 CronTrigger

 CronTrigger 是 APScheduler 中一个非常强大的触发器，它允许你使用类 Unix-cron 的表达式来调度任务，能够精确到秒，并能通过指定特定时间间隔、日期范围等来进行复杂的调度。

Cron 表达式的基本格式

*    *    *    *    *    *    
-    -    -    -    -    -
|    |    |    |    |    |
|    |    |    |    |    +----- day of the week (0 - 6) (Sunday=0)
|    |    |    |    +---------- month (1 - 12)
|    |    |    +--------------- day of the month (1 - 31)
|    |    +-------------------- hour (0 - 23)
|    +------------------------- minute (0 - 59)
+------------------------------ second (0 - 59) (optional)

Cron 表达式的特殊字符 

• * 表示所有可能的值。例如，* 在 minute 字段表示每一分钟都会触发。
• */X 表示每隔 X 单位触发。例如，*/5 在 minute 字段表示每五分钟触发一次。
• X-Y 表示从 X 到 Y 的范围内触发。例如，10-12 在 hour 字段表示每天 10 点到 12 点触发。
• X,Y,Z 表示 X、Y 和 Z 时间点触发。例如，1,2,3 在 day 字段表示每月 1、2、3 日触发。

CronTrigger 的参数

• year：四位数的年份。
• month：1-12 或 jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec。
• day：1-31。
• week：1-53。
• day_of_week：0-6（0 是周日）或 mon, tue, wed, thu, fri, sat, sun。
• hour：0-23。
• minute：0-59。
• second：0-59。
• start_date：开始日期时间（包含）。
• end_date：结束日期时间（包含）。
• timezone：指定时区。

 示例：简单 ——>复杂

 每天中午 12 点执行任务

scheduler.add_job(my_job, 'cron', hour=12, minute=0)

每周一到周五的上午 8 点执行任务

scheduler.add_job(my_job, 'cron', day_of_week='mon-fri', hour=8, minute=0)

 每月 1 号和 15 号的晚上 9 点执行任务

scheduler.add_job(my_job, 'cron', day='1,15', hour=21, minute=0)

每隔 10 分钟执行一次任务

scheduler.add_job(my_job, 'cron', minute='*/10')

在指定日期范围内每天中午 12 点执行任务

scheduler.add_job(my_job, 'cron', start_date='2024-07-16', end_date='2024-08-24', hour=12, minute=0)

每月最后一天的午夜执行任务

scheduler.add_job(my_job, 'cron', day='last', hour=0, minute=0)

每季度的第一个月（1, 4, 7, 10）的最后一个星期五的下午 3 点执行任务

scheduler.add_job(my_job, 'cron', month='1,4,7,10', day='last fri', hour=15, minute=0)

每天的 9 点到 17 点之间每隔 2 小时执行一次任务

scheduler.add_job(my_job, 'cron', hour='9-17/2', minute=0)

 在特定日期时间范围内每周三和周五的早上 6 点执行任务

scheduler.add_job(my_job, 'cron', day_of_week='wed,fri', hour=6, start_date='2024-07-01', end_date='2024-12-31')

 CalendarIntervalTrigger

CalendarIntervalTrigger 类似于 IntervalTrigger，但它基于日历时间间隔进行调度。与 IntervalTrigger 不同，它考虑了实际的日历时间。

日历时间间隔参数

• years: 间隔的年数
• months: 间隔的月数
• weeks: 间隔的周数
• days: 间隔的天数
• hours: 间隔的小时数
• minutes: 间隔的分钟数
• seconds: 间隔的秒数
• start_date: 开始运行任务的时间
• end_date: 停止运行任务的时间
• timezone: 使用的时区

示例 

每月的第一个星期一运行一次任务

trigger = CalendarIntervalTrigger(months=1, start_date='2023-01-01 00:00:00', timezone='UTC')
scheduler.add_job(my_job, trigger)

 每月的第一个星期一上午9点执行任务

from datetime import datetime
import pytz

trigger = CalendarIntervalTrigger(months=1, start_date='2023-01-01 09:00:00', timezone=pytz.utc)
scheduler.add_job(my_job, trigger)

 每年的1月1日执行任务

trigger = CalendarIntervalTrigger(years=1, start_date='2023-01-01 00:00:00', timezone='UTC')
scheduler.add_job(my_job, trigger)

综上所述，搞定cron，那就搞定一切了。。。