跳到主要内容

3. 模块概述 (Module Overview)

3.1. 特性 (Features)​

ietf-schedule 数据模型 (data model) 使用模块化方法定义与重复相关的分组 (recurrence-related groupings). 为此, 它定义了从基本到高级, 即类似 iCalendar 的规则 (iCalendar-like rules), 多种重复分组表示形式. 为了允许不同选项, 该数据模型定义了两个特性:

  • basic-recurrence

  • icalendar-recurrence

这些特性的使用见第 3.4 节和附录 B.1.

3.2. 类型和身份 (Types and Identities)​

ietf-schedule 模块 (第 6 节) 定义了以下身份 (identities):

  • schedule-type: 指示调度的类型. 目前定义了以下类型:

    • one-shot: 此类型用于触发某个操作的调度, 该操作的持续时间指定为 0, 或结束时间指定为与开始时间相同. 之后, 该调度将禁用自身 ([RFC3231] 第 3.3 节).

    • period: 此类型用于基于时段的调度, 该调度由以下两者之一组成: (1) 开始和结束, 或 (2) 开始和正持续时间. 如果既未指示结束也未指示持续时间, 则认为该时段永久持续.

    • recurrence: 此类型用于基于重复的调度. 重复可以是周期性的, 即在相同时段上重复, 例如每五分钟一次. 重复也可以是非周期性的, 即以非规则方式重复, 例如每天上午 8 点和 9 点.

  • frequency-type: 表征重复调度的重复间隔规则, 例如每秒, 每分钟等.

  • schedule-state: 指示调度的状态, 例如已启用, 已禁用, 冲突, 已完成等. 此身份还可用于管理基于重复的调度中各个实例的状态.

  • discard-action-type: 指定当请求的调度因任何原因无法被接受并被丢弃时, 响应方要采取的操作, 例如生成警告或错误消息.

3.3. 调度分组 (Scheduling Groupings)​

ietf-schedule 模块 (第 6 节) 定义了以下分组 (groupings):

  • generic-schedule-params (第 3.3.1 节)

  • period-of-time (第 3.3.2 节)

  • recurrence-basic (第 3.3.3 节)

  • recurrence-utc (第 3.3.4 节)

  • recurrence-with-time-zone (第 3.3.5 节)

  • recurrence-utc-with-periods (第 3.3.6 节)

  • recurrence-time-zone-with-periods (第 3.3.7 节)

  • icalendar-recurrence (第 3.3.8 节)

  • schedule-status, schedule-status-with-time-zone, 以及 schedule-status-with-name (第 3.3.9 节)

示例见附录 A.

3.3.1. generic-schedule-params 分组 (The generic-schedule-params Grouping)​

系统接受并处理调度请求, 这有助于根据日期和时间进一步自动化事件, 策略, 服务或资源的调度过程. generic-schedule-params 分组 (图 1) 指定了一组配置参数, 系统使用这些参数来验证请求的调度.

  grouping generic-schedule-params:
    +-- description?            string
    +-- time-zone-identifier?   sys:timezone-name
    +-- validity?               yang:date-and-time
    +-- max-allowed-start?      yang:date-and-time
    +-- min-allowed-start?      yang:date-and-time
    +-- max-allowed-end?        yang:date-and-time
    +-- discard-action?         identityref

     Figure 1: 'generic-schedule-params' Grouping Tree Structure

description 参数包含调度的描述. 本文档不对此参数的结构或使用施加约束.

如果提供了 time-zone-identifier 参数, 它指定本地日期和时间值的时区引用 [RFC7317]. 如果任何日期和时间值采用本地时间格式, 则必须指定此参数. 此参数禁止应用于以 UTC 格式或相对于 UTC 的时区偏移格式指定的日期和时间值.

validity 参数指定某个调度在其后不再被视为有效的日期和时间. 它确定调度可开始并因此执行的最晚时间, 与该调度何时结束无关, 并且优先于调度实例自身提供的类似属性. 请求的调度仍可能被接受, 但任何晚于已配置值开始的发生项都不会执行.

max/min-allowed-start 参数指定最大/最小已调度开始日期和时间. 如果调度的第一次发生晚于/早于已配置值开始, 则请求的调度将被拒绝.

max-allowed-end 参数指定最后一次发生允许的最大结束时间. 如果最后一次发生的结束时间晚于已配置的 max-allowed-end 值, 则请求的调度将被拒绝.

discard-action 参数指定当请求的调度因任何原因无法被接受并被丢弃时要采取的操作. 可能的原因包括但不限于, 请求的调度未能满足此分组中的保护条件, 与现有调度冲突, 或已经过期, 例如预期开始时间已经过去.

这些参数适用于系统上的所有调度, 旨在提供保护, 用于防止陈旧配置, 过短而会阻止管理员验证某些关键系统的调度请求等情况.

3.3.2. period-of-time 分组 (The period-of-time Grouping)​

period-of-time 分组 (图 2) 使用开始日期和时间 (period-start) 与结束日期和时间 (period-end), 或使用开始日期和时间 (period-start) 与非负时间持续时间 (duration) 来表示一个时间段. 对于第一种格式, 时段的开始时间必须不晚于时段的结束时间. 如果既未指示结束日期和时间 (period-end) 也未指示持续时间 (duration), 则认为该时段永久持续. 如果持续时间 (duration) 值为 0, 或结束时间 (period-end) 与开始时间 (period-start) 相同, 则认为该时段是一次性调度 (one-shot schedule). 如果未指定开始日期和时间 (period-start), 则认为该时段立即开始.

time-zone-identifier 参数指示时区的标识符. 如果 period-start 或 period-end 值以本地时间格式报告, 则必须指定此参数. 此参数禁止应用于以 UTC 格式或相对于 UTC 的时区偏移格式指定的日期和时间值.

period-description 参数包含该时段的描述. 本文档不对此参数的结构或使用施加约束.

  grouping period-of-time:
    +-- period-description?     string
    +-- period-start?           yang:date-and-time
    +-- time-zone-identifier?   sys:timezone-name
    +-- (period-type)?
       +--:(explicit)
       |  +-- period-end?       yang:date-and-time
       +--:(duration)
          +-- duration?         duration

          Figure 2: 'period-of-time' Grouping Tree Structure

3.3.3. recurrence-basic 分组 (The recurrence-basic Grouping)​

recurrence-basic 分组 (图 3) 指定一个立即开始并永久重复的简单重复规则.

  grouping recurrence-basic:
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32

         Figure 3: 'recurrence-basic' Grouping Tree Structure

频率参数 (frequency) 标识重复规则的类型. 例如, daily 频率值指定基于一天或更长间隔的重复事件.

与 [RFC5545] 第 3.3.10 节一致, 间隔参数 (interval) 表示重复规则以何种间隔重复. 例如, 在 daily 重复规则中, 8 的间隔值表示每八天一次.

注意, 根据 [YANG-GUIDE] 第 4.13 节, 这里没有为 frequency 和 interval 参数定义 default 子语句, 因为在某些场景下, 例如剖面化 (profiling), 使用这些语句存在问题. 出于同样原因, 这里也没有定义 mandatory 子语句. 使用此分组的 YANG 模块如果始终需要配置这两个节点或始终需要默认值, 应当使用 mandatory 或 default 语句之一细化这两个节点. 在此分组由另一个分组使用等情况下, 可以忽略此建议.

recurrence-description 参数包含该时段的描述. 本文档不对此参数的结构或使用施加约束.

3.3.4. recurrence-utc 分组 (The recurrence-utc Grouping)​

recurrence-utc 分组 (图 4) 使用 recurrence-basic 分组 (第 3.3.3 节), 并以 UTC 格式指定一个简单重复规则.

  grouping recurrence-utc:
    +-- recurrence-first
    |  +-- start-time-utc?   yang:date-and-time
    |  +-- duration?         uint32
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- utc-until?          yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32

          Figure 4: 'recurrence-utc' Grouping Tree Structure

start-time-utc 参数指示 UTC 格式的开始时间.

duration 参数以秒为单位指定第一次发生的时间段. 除非另有指定, 例如通过额外的扩充参数指定, duration 也适用于后续重复实例. 未指定时, 每次发生被视为立即完成, 例如执行一个被认为会快速完成的即时命令, 或者被视为难以计算准确持续时间, 例如运行一个数据分析脚本, 其执行时间可能取决于数据量和计算资源可用性. 当任务花费的时间超过 duration 指定的时间时应遵循的行为不在本文档范围内. 此类考虑属于任务管理, 而不是调度管理.

注意, interval 和 duration 覆盖调度事件的两个不同属性. interval 与频率参数结合使用, 指定调度何时发生, 而 duration 指示一次发生持续多长时间. 本文档允许发生项之间的间隔短于每个发生项的持续时间, 例如某个重复事件被调度为每天开始一次, 每次持续 2 天.

重复可以通过指定结束时间或通过发生次数进行限定, 由 recurrence-end 选择 (choice) 指示. count 值必须大于 1, 并且 start-time-utc 值始终计为第一次发生.

recurrence-utc 分组设计用于在更需要机器可读性的调度上下文中复用.

3.3.5. recurrence-with-time-zone 分组 (The recurrence-with-time-zone Grouping)​

recurrence-with-time-zone 分组 (图 5) 使用 recurrence-basic 分组 (第 3.3.3 节), 并指定带有时区的简单重复规则.

  grouping recurrence-with-time-zone:
    +-- recurrence-first
    |  +-- start-time?   yang:date-and-time
    |  +-- duration?     duration
    +-- time-zone-identifier?     sys:timezone-name
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32

    Figure 5: 'recurrence-with-time-zone' Grouping Tree Structure

recurrence-first 容器包含 start-time 和 duration 参数, 用于指定第一次发生的开始时间和时段. 除非另有指定, 例如通过额外的扩充参数指定, duration 也适用于后续重复实例. 未指定时, 每次发生被视为立即完成, 例如执行一个被认为会快速完成的即时命令, 或者被视为难以计算准确持续时间, 例如运行一个数据分析脚本, 其执行时间可能取决于数据量和计算资源可用性.

该分组还包含 time-zone-identifier 参数. 如果 start-time 或 until 值以本地时间格式报告, 则必须指定该参数. 此参数禁止应用于以 UTC 格式或相对于 UTC 的时区偏移格式指定的日期和时间值.

重复可以通过指定结束时间或通过发生次数进行限定, 由 recurrence-end 选择指示. count 值必须大于 1, 并且 start-time 值始终计为第一次发生.

第 3.3.4 节中关于 interval 和 duration 的考虑同样适用于 recurrence-with-time-zone.

与 recurrence-utc 分组 (第 3.3.4 节) 的定义不同, recurrence-with-time-zone 旨在优先提升人类可读性, 而非机器可读性.

3.3.6. recurrence-utc-with-periods 分组 (The recurrence-utc-with-periods Grouping)​

recurrence-utc-with-periods 分组 (图 6) 使用 recurrence-utc 分组 (第 3.3.4 节), 并添加 period-timeticks 列表来定义重复发生项的聚合集合.

  grouping recurrence-utc-with-periods:
    +-- recurrence-first
    |  +-- start-time-utc?   yang:date-and-time
    |  +-- duration?         uint32
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- utc-until?          yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32
    +-- period-timeticks* [period-start]
       +-- period-start    yang:timeticks
       +-- period-end?     yang:timeticks

   Figure 6: 'recurrence-utc-with-periods' Grouping Tree Structure

重复实例由重复规则和 period-timeticks 列表共同定义的发生项的并集指定. 此列表使用 [RFC9911] 中定义的 yang:timeticks 类型. 重复实例会被忽略. period-start 实例的值禁止超过 frequency 实例的值, 即在每秒重复规则中, timeticks 值不得超过 100, 在每分钟重复规则中不得超过 6000, 依此类推.

3.3.7. recurrence-time-zone-with-periods 分组 (The recurrence-time-zone-with-periods Grouping)​

recurrence-time-zone-with-periods 分组 (图 7) 使用 recurrence-with-time-zone 分组 (第 3.3.5 节), 并添加 period 列表来定义重复发生项的聚合集合.

  grouping recurrence-time-zone-with-periods:
    +-- recurrence-first
    |  +-- start-time?   yang:date-and-time
    |  +-- duration?     duration
    +-- time-zone-identifier?     sys:timezone-name
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32
    +-- period* [period-start]
       +-- period-description?     string
       +-- period-start            yang:date-and-time
       +-- time-zone-identifier?   sys:timezone-name
       +-- (period-type)?
          +--:(explicit)
          |  +-- period-end?       yang:date-and-time
          +--:(duration)
             +-- duration?         duration

Figure 7: 'recurrence-time-zone-with-periods' Grouping Tree Structure

重复实例由重复规则和 period 列表共同定义的发生项的并集指定. 重复实例会被忽略.

3.3.8. icalendar-recurrence 分组 (The icalendar-recurrence Grouping)​

icalendar-recurrence 分组 (图 8) 使用 recurrence-time-zone-with-periods 分组 (第 3.3.7 节), 并定义更多数据节点来丰富重复定义. icalendar-recurrence 分组的结构参考 [RFC5545] 第 3.3.10 节和第 3.8.5 节中定义的重复组件.

  grouping icalendar-recurrence:
    +-- recurrence-first
    |  +-- start-time?   yang:date-and-time
    |  +-- duration?     duration
    +-- time-zone-identifier?     sys:timezone-name
    +-- (recurrence-end)?
    |  +--:(until)
    |  |  +-- until?              yang:date-and-time
    |  +--:(count)
    |     +-- count?              uint32
    +-- recurrence-description?   string
    +-- frequency?                identityref
    +-- interval?                 uint32
    +-- period* [period-start]
    |  +-- period-description?     string
    |  +-- period-start            yang:date-and-time
    |  +-- time-zone-identifier?   sys:timezone-name
    |  +-- (period-type)?
    |     +--:(explicit)
    |     |  +-- period-end?       yang:date-and-time
    |     +--:(duration)
    |        +-- duration?         duration
    +-- bysecond*                 uint32
    +-- byminute*                 uint32
    +-- byhour*                   uint32
    +-- byday* [weekday]
    |  +-- direction*   int32
    |  +-- weekday      schedule:weekday
    +-- bymonthday*               int32
    +-- byyearday*                int32
    +-- byyearweek*               int32
    +-- byyearmonth*              uint32
    +-- bysetpos*                 int32
    +-- workweek-start?           schedule:weekday
    +-- exception-dates*          yang:date-and-time

       Figure 8: 'icalendar-recurrence' Grouping Tree Structure

bysecond 数组, 或 byminute 或 byhour 数组, 指定一分钟内的秒列表, 或一小时内的分钟列表, 或一天中的小时列表. 例如, 在 minutely 重复规则中, byminute 节点值 10 和 20 表示发生项在一小时内第 10 分钟和第 20 分钟生成, 从而将重复实例数量从所有分钟减少到指定分钟.

byday 参数指定一周中各天的列表, 并可带有可选方向, 该方向指示在 monthly 或 yearly 频率实例中特定日期的第 n 次出现. 在 monthly 重复规则中, direction 的有效值为 1 到 5 或 -5 到 -1. 在 yearly 重复规则中, 有效值为 1 到 53 或 -53 到 -1. 例如, 在 monthly 规则中, 值为 monday 的 weekday 与值为 -1 的 direction 表示该月的最后一个星期一.

bymonthday 数组, 或 byyearday, byyearweek, byyearmonth 数组, 指定月中的日期列表, 或年中的日期列表, 年中的周列表, 年中的月份列表. 例如, 在 yearly 重复规则中, byyearmonth 实例值 1 和 2 表示发生项在一月和二月生成, 从而将 yearly 重复从每年一次增加为每年一月和二月各发生.

bysetpos 传达一个值列表, 该列表对应于所指定重复实例集合中的第 n 个发生项. 例如, 在 monthly 重复规则中, byday 数据节点指定每周一, 而值为 -1 的 bysetpos 表示该月的最后一个星期一. 不设置 bysetpos 数据节点表示该月的每个星期一.

workweek-start 数据节点指定一周开始于哪一天. 当 weekly 重复规则的间隔大于 1 且指定了 byday 数据节点时, 这很重要. 当处于 yearly 规则且指定了 byyearweek 时, 这也很重要. 注意, 根据 [YANG-GUIDE] 第 4.13 节, 这里没有定义 default 子语句, 因为在某些场景下, 例如剖面化, 使用这些语句存在问题. 出于同样原因, 这里也没有定义 mandatory 子语句. 使用此分组的 YANG 模块如果始终需要配置 workweek-start 节点或始终需要默认值, 应当使用 mandatory 或 default 语句之一细化该节点. 在此分组由另一个分组使用等情况下, 可以忽略这一点.

exception-dates 数据节点指定重复的例外列表. 最终的重复集合通过收集由任何指定重复规则和日期时间创建的所有日期和时间值, 然后排除由 exception-dates 参数指定的任何开始日期和时间值来生成.

3.3.9. schedule-status, schedule-status-with-time-zone, 以及 schedule-status-with-name 分组 (The schedule-status, schedule-status-with-time-zone, and schedule-status-with-name Groupings)​

schedule-status, schedule-status-with-time-zone, 以及 schedule-status-with-name 分组 (图 9) 定义了用于调度管理/状态暴露的通用参数. schedule-status-with-time-zone 分组与 schedule-status 具有相同结构, 但增加了一个用于标识时区的参数. 类似地, schedule-status-with-name 分组与 schedule-status 具有相同结构, 但增加了一个用于标识调度 schedule-name 的参数. 这些结构在模块中定义, 以实现更好的模块化和灵活性.

  grouping schedule-status:
    +-- state?                    identityref
    +-- version?                  uint16
    +-- schedule-type?            identityref
    +--ro local-time?               yang:date-and-time
    +--ro last-update?              yang:date-and-time
    +--ro counter?                  yang:counter32
    +--ro last-occurrence?          yang:date-and-time
    +--ro upcoming-occurrence?      yang:date-and-time
    +--ro last-failed-occurrence?   yang:date-and-time
    +--ro failure-counter?          yang:counter32
  grouping schedule-status-with-time-zone:
    +--ro time-zone-identifier?  sys:timezone-name
    +-- schedule-name?            string
    +-- state?                    identityref
    +-- version?                  uint16
    +-- schedule-type?            identityref
    +--ro local-time?               yang:date-and-time
    +--ro last-update?              yang:date-and-time
    +--ro counter?                  yang:counter32
    +--ro last-occurrence?          yang:date-and-time
    +--ro upcoming-occurrence?      yang:date-and-time
    +--ro last-failed-occurrence?   yang:date-and-time
    +--ro failure-counter?          yang:counter32
  grouping schedule-status-with-name:
    +-- schedule-name?            string
    +-- state?                    identityref
    +-- version?                  uint16
    +-- schedule-type?            identityref
    +--ro local-time?               yang:date-and-time
    +--ro last-update?              yang:date-and-time
    +--ro counter?                  yang:counter32
    +--ro last-occurrence?          yang:date-and-time
    +--ro upcoming-occurrence?      yang:date-and-time
    +--ro last-failed-occurrence?   yang:date-and-time
    +--ro failure-counter?          yang:counter32

        Figure 9: 'schedule-status-*' Groupings Tree Structure

如果存在多个调度上下文, schedule-name 参数有助于在网络设备或控制器中唯一标识一个调度.

state 参数定义为根据分组的使用方式配置/暴露调度状态. 对于基于重复的调度, 它表示整体重复的状态. 此参数使用 identityref 类型, 以允许未来模块中的可扩展性.

version 参数用于跟踪当前调度版本信息. 创建调度的实体可以递增该版本. last-update 参数标识调度最后一次修改的时间. 在某些上下文中, 此参数可用于跟踪给定调度的配置. 在这些情况下, version 可以不使用.

schedule-type 参数标识当前调度的类型. counter, last-occurrence, 以及 upcoming-occurrence 数据节点仅在 schedule-type 为 recurrence 时可用.

当未包含时区时, local-time 报告托管调度的实体所看到的实际本地时间. 控制器可以使用此参数推断相对于 UTC 的偏移量. 此用法类似于 [RFC3231] 中 schedLocalTime 的用法.

last-failed-occurrence 和 failure-counter 报告此调度发生的最后一次失败以及失败次数. 除非定义了新的参数/操作以允许重置失败次数, 否则默认情况下, failure-counter 仅在调度开始时重置.

当前分组捕获了适用于目前已知典型调度上下文的通用参数. 未来模块可以根据需要定义其他有用参数. 例如, 在具有多个系统来源来提供调度的调度上下文中, 可能需要 source 和 precedence 参数来反映应如何对来自不同来源的调度进行优先级排序.

3.4. 特性使用和扩充 (Features Use and Augmentations)​

附录 B.1 提供了一个示例, 说明如何使用第 3.1 节中定义的特性. 实现可以根据需要通过声明不同特性来支持基本重复规则或高级重复规则. 仅支持一个特性还是同时支持两个特性由实现决定, 并取决于具体的调度上下文.

通用调度分组 (第 3.3 节) 也可以被扩充以支持特定需求. 例如, 附录 B.2 展示了如何添加额外参数以符合特定调度需求.

最后于 更新