AWX Project Schedules API 详解：rrule 格式规范与项目定时任务实战

AWX Project Schedules API 详解：rrule 格式规范与项目定时任务实战

发布时间：2026/9/27 12:42:55
AWX Project Schedules API 详解：rrule 格式规范与项目定时任务实战 AWX Project Schedules API 详解rrule 格式规范与项目定时任务实战【免费下载链接】awxAWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is one of the upstream projects for Red Hat Ansible Automation Platform.项目地址: https://gitcode.com/gh_mirrors/aw/awx导读Project Schedules项目调度是 AWX 中用于让 Project项目按指定时间规律自动触发 SCM 更新等操作的核心能力。本文以 AWX 仓库中的 API 文档模板awx/api/templates/api/project_schedules_list.md为主体骨架系统讲解该端点支持的 GET 列表、POST 创建两种操作并深入剖析其底层rruleiCalendar 循环规则的格式约束、校验逻辑与示例。读完本文你将掌握如何通过 REST API 为 Project 创建定时更新调度并能准确写出通过校验的rrule字符串。端点概览Project Schedules 能做什么在 AWX 中ProjectSchedulesList视图对应路由project_schedules_list注册于 awx/api/urls/project.py#L35re_path(r^(?Ppk[0-9])/schedules/$, ProjectSchedulesList.as_view(), nameproject_schedules_list),也就是说对单个 Project 的调度端点形如GET/POST /api/v2/projects/{id}/schedules/。该视图定义于 awx/api/views/init.py#L1016class ProjectSchedulesList(SubListCreateAPIView): name _(Project Schedules) model models.Schedule serializer_class serializers.ScheduleSerializer parent_model models.Project relationship schedules parent_key unified_job_template resource_purpose schedules of a project关键点在于parent_key unified_job_templateProject 通过UnifiedJobTemplate统一作业模板基类与Schedule模型关联而Schedule模型上的外键unified_job_template见 awx/main/models/schedules.py#L131正是这种关系的落点。因此Project Schedules 本质上是挂在统一作业模板上的定时触发规则其触发的动作是 Project Update项目更新。从模板继承关系看project_schedules_list.md继承自 sub_list_create_api_view.md后者又引入 sub_list_api_view.md从而形成列表 创建两个操作的文档结构。GET列出某 Project 下的所有调度对GET /api/v2/projects/{id}/schedules/发起请求即可检索与所选 Project 关联的全部调度。该列表是标准的分页列表返回的是 ScheduleSerializer 序列化后的字段集合。Schedule模型awx/main/models/schedules.py#L123的核心字段如下字段类型说明unified_job_templateForeignKey关联的作业模板此处为 Project同一模板下调度名唯一unique_together (unified_job_template, name)nameCharField(max_length512)调度名称enabledBooleanField(defaultTrue)是否启用该调度关闭后不再处理rruleTextFieldiCalendar 格式的循环规则字符串即本文重点dtstartDateTimeField计算字段表示首次执行时间大于等于该时间的第一次出现dtendDateTimeField计算字段表示最后一次执行时间之后调度过期next_runDateTimeField计算字段下一次执行时间timezone/until只读属性由rrule推导出的时区与结束时间其中timezone属性awx/main/models/schedules.py#L167会解析rrule中DTSTART的时区信息若为 UTC 直接返回UTC否则通过 zoneinfo 数据库反查时区名。列表默认按next_run降序排列null 值排最后。POST为 Project 创建新调度对同一端点发起POST请求可在指定 Project 下创建新的调度需提交调度相关字段。POST 请求的rrule值必须遵循特定格式且仅允许规则集的一个子集详细约束见下文。关于关联语义需要区分两点由于本端点parent_key unified_job_template创建出的 Schedule 直接与 Project经统一作业模板绑定若父模型字段不同同一文档模板族中的其他子列表端点如job_template_schedules_list、inventory_source_schedules_list参见 awx/api/templates/api/ 下的同名模板会呈现关联/取消关联已有对象的语义而 Project Schedules 走的是直接创建路径。调度一旦创建并启用AWX 的调度器awx/main/scheduler目录会依据next_run到期触发Schedule.get_job_kwargs()awx/main/models/schedules.py#L284会基于调度的prompts_dict()配置拼接作业参数并以launch_type: scheduled、schedule: self的方式标记作业来源。rrule 格式规范AWX 支持的规则子集POST 请求中的rrule必须符合以下格式与约束出自 awx/api/templates/api/_schedule_detail.mdDTSTART必填且必须采用DTSTART:YYYYMMDDTHHMMSSZ格式DTSTART必须为 UTC 时间INTERVAL必填不支持SECONDLY按秒RRULE关键字必须位于规则语句之前BYDAY受支持但不支持带数字前缀的形式如20MOBYYEARDAY与BYWEEKNO不支持每条调度只支持一条RRULE语句COUNT必须小于 1000。这些约束在序列化器层有严格对等的实现。ScheduleSerializer.validate_rruleawx/api/serializers.py#L5687会逐条拒绝缺少DTSTART提示必须以DTSTART:YYYYMMDDTHHMMSSZ开头DTSTART为 naive datetime缺少时区提示DTSTART cannot be a naive datetime出现多个DTSTART提示Multiple DTSTART is not supported未包含rrule:关键字提示One or more rule required in rrule包含exdate:EXDATE not allowed in rrule包含rdate:RDATE not allowed in rrule规则中缺少INTERVAL或INTERVAL不是正整数使用了secondlyBYDAY带数字前缀正则.*?BYDAY[\:\][0-9][a-zA-Z]{2}命中即拒绝COUNT 999提示COUNT 999 is unsupported最终通过Schedule.rrulestr(rrule_value)做整体解析解析失败则报rrule parsing failed validation。校验通过后调度写入数据库。Schedule.rrulestrawx/main/models/schedules.py#L257还封装了自定义解析逻辑先将UNTIL中按 RFC5545 允许的纯日期形式naive强制转换为与DTSTART一致的时区感知形式coerce_naive_until见 awx/main/models/schedules.py#L197再交给底层 rrule 库解析为rruleset为next_run、dtstart、dtend等计算字段提供依据。rrule 示例全集与解读以下是文档中给出的 13 条合法rrule示例覆盖了从分钟级一次性到按年的常见调度需求可直接作为 POST 请求体中的rrule值使用DTSTART:20500331T055000Z RRULE:FREQMINUTELY;INTERVAL10;COUNT5 DTSTART:20240331T075000Z RRULE:FREQDAILY;INTERVAL1;COUNT1 DTSTART:20140331T075000Z RRULE:FREQMINUTELY;INTERVAL1;UNTIL20230401T075000Z DTSTART:20140331T075000Z RRULE:FREQWEEKLY;INTERVAL1;BYDAYMO,WE,FR DTSTART:20140331T075000Z RRULE:FREQWEEKLY;INTERVAL5;BYDAYMO DTSTART:20140331T075000Z RRULE:FREQMONTHLY;INTERVAL1;BYMONTHDAY6 DTSTART:20140331T075000Z RRULE:FREQMONTHLY;INTERVAL1;BYSETPOS4;BYDAYSU DTSTART:20140331T075000Z RRULE:FREQMONTHLY;INTERVAL1;BYSETPOS-1;BYDAYMO,TU,WE,TH,FR DTSTART:20140331T075000Z RRULE:FREQMONTHLY;INTERVAL1;BYSETPOS-1;BYDAYMO,TU,WE,TH,FR,SA,SU DTSTART:20140331T075000Z RRULE:FREQYEARLY;INTERVAL1;BYMONTH4;BYMONTHDAY1 DTSTART:20140331T075000Z RRULE:FREQYEARLY;INTERVAL1;BYSETPOS-1;BYMONTH8;BYDAYSU DTSTART:20140331T075000Z RRULE:FREQWEEKLY;INTERVAL1;UNTIL20230401T075000Z;BYDAYMO,WE,FR DTSTART:20140331T075000Z RRULE:FREQHOURLY;INTERVAL1;UNTIL20230610T075000Z逐条解读第 1 条从 2050-03-31 05:50:00UTC起每 10 分钟触发一次共 5 次COUNT限次适合一次性短周期任务。第 2 条每天一次、只触发 1 次等价于仅执行一次的日调度写法。第 3 条每分钟触发直到UNTIL20230401T075000Z为止UNTIL定终止时间与COUNT二选一。第 4 条每周一、三、五各触发一次BYDAY多值并列。第 5 条每 5 周触发一次仅限周一。第 6 条每月 6 日触发一次BYMONTHDAY指定月内日。第 7 条每月第 4 个星期日触发BYSETPOS4BYDAYSU组合出第几个星期几。第 8 条每月最后一个工作日周一至周五触发BYSETPOS-1表示倒数第一个BYDAYMO,TU,WE,TH,FR限定工作日。第 9 条每月最后一天触发BYSETPOS-1 周一到周日全量。第 10 条每年 4 月 1 日触发。第 11 条每年 8 月的最后一个星期日触发BYMONTH8BYSETPOS-1BYDAYSU典型的某月最后一个星期几写法。第 12 条每周一、三、五触发且受UNTIL截止时间约束UNTIL与BYDAY可同时出现。第 13 条每小时触发一次直到 2023-06-10 07:50:00UTC为止。一个常见的 POST 请求体示例为某 Project 创建每天 07:50 UTC 更新一次的调度形如{ name: nightly-project-update, rrule: DTSTART:20240331T075000Z RRULE:FREQDAILY;INTERVAL1;COUNT1, enabled: true }注意DTSTART是调度的生效起点而非首次执行时间本身首次执行发生在DTSTART之后按规则计算出的第一个时刻即next_run字段所标示的时间。若希望调度长期有效可用UNTIL或省略终止条件若只需要有限次数用COUNT须小于 1000。校验与调试用源码确认边界如果你需要预演某条rrule能产生多少次执行AWX 还提供了SchedulePreviewSerializerawx/api/serializers.py#L5671它接收rrule并复用同一套validate_rrule逻辑返回按该规则计算出的未来执行时间序列适合在创建调度前进行预览验证。提交rrule时若违反上述任一约束API 会返回 400 及具体的错误消息如COUNT 999 is unsupported、Multiple DTSTART is not supported。因此实践中的要点可以归纳为永远以DTSTART:YYYYMMDDTHHMMSSZUTC开头永远在RRULE:之后声明FREQ与INTERVAL避免SECONDLY、BYYEARDAY、BYWEEKNO、带数字前缀的BYDAY、EXDATE、RDATECOUNT控制在 999 以内且不要与UNTIL同时使用一条调度只写一条RRULE语句。文档模板体系这份规范从哪里来project_schedules_list.md本身是 AWX 自动生成 API 文档体系中的一个 Jinja2 模板它继承sub_list_create_api_view.md获得 GET 列表与 POST 创建的结构骨架再通过{% block post_create %}引入 _schedule_list_common.md后者强调POST 请求必须包含符合格式约束的rrule并继续引入 _schedule_detail.md 展开 rrule 的完整格式细则。相同的调度模板块还被schedule_list.md、job_template_schedules_list.md、inventory_source_schedules_list.md复用见 awx/api/templates/api/这意味着本文讲解的 rrule 约束不仅适用于 Project也适用于 Job Template、Inventory Source 等所有挂载调度的资源一通则百通。小结Project Schedules 端点把定时更新项目这一高频运维诉求收敛为一次简单的POST只要提交合法的rruleAWX 就会持久化调度、计算next_run并在到期时自动发起带launch_typescheduled标记的项目更新作业。理解rrule的格式子集UTC 的DTSTART、必填的INTERVAL、受限制的BYDAY/BYSETPOS/COUNT与序列化器层的逐项校验是写出稳定可用的定时任务的第一步也是排查 400 报错的关键依据。【免费下载链接】awxAWX provides a web-based user interface, REST API, and task engine built on top of Ansible. It is one of the upstream projects for Red Hat Ansible Automation Platform.项目地址: https://gitcode.com/gh_mirrors/aw/awx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考