Home Assistant Schedule 集成实战：使用 schedule.get_schedule 动作读取每周时间计划-育师

Home Assistant Schedule 集成实战：使用 schedule.get_schedule 动作读取每周时间计划

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

导读

schedule.get_schedule是 Home Assistant 中 Schedule（每周时间计划）集成提供的核心动作，用于一次性读取一个或多个 schedule 实体已配置的全部时间段（time ranges），并将结果写入响应变量（response variable），供同一自动化或脚本的后续步骤使用。读完本文，你将掌握在 UI 与 YAML 两种方式下调用该动作、解析其响应数据结构、以及结合模板（Templating）把"今天的计划"动态拼进通知消息的完整实战方案。

schedule.get_schedule 动作概览

在动作文档中，该动作被定义为：

动作名称：schedule.get_schedule
所属域：schedule
功能描述：检索一个或多个 schedule 已配置的时间范围
典型用途：例如把今天的 schedule 时间范围放进一条通知消息中
关键特性：可以在一次调用中读取多个 schedule；结果通过响应变量返回，可在同一自动化或脚本的后续步骤中继续使用

与其他"执行后无返回"的动作不同，schedule.get_schedule属于带响应数据的动作。这类动作返回的数据通常是动态的、体量较大的信息（如未来一周的日历事件、详细的行程路线），不适合长期存放在实体状态中，因此以响应数据的形式在动作执行时一次性返回。关于响应变量机制的通用说明，可参考执行动作（Actions）文档。

前置条件：理解 Schedule 集成的数据模型

要正确解读schedule.get_schedule的返回结果，先要理解它所读取的数据从何而来。Schedule 集成（集成文档）允许你创建"每周时间计划"实体：为每一天设置若干时间段（time block），每个时间段有明确的开始时间（from）与结束时间（to）。时间块开始时 schedule 实体变为激活（on）状态，时间块结束时变为非激活（off）状态，因此 schedule 常被用作自动化中的触发器或条件。

通过 UI 创建 schedule

在 UI 中配置 schedule 时，可设置：

配置项	说明
`Name`	schedule 的友好名称
`Icon`	前端中为该 schedule 显示的图标
`Schedule blocks`	按住并拖动鼠标，为每周的每一天选择时间块；同一天不允许创建重叠的时间块

创建时间块后，点击某个时间块可编辑其细节：

配置项	必填	类型	说明
`Start`	是	time	开始时间，届时 schedule 变为激活/开启
`End`	是	time	结束时间，届时变为非激活/关闭
`Additional data`	否	map	属性名到值的映射；该时间块激活时，这些键值会作为属性附加到实体上

通过 YAML 创建 schedule

也可以在configuration.yaml中手动配置 schedule，例如（出自集成文档）：

schedule: light_schedule: name: "Light schedule" wednesday: - from: "17:00:00" to: "21:00:00" data: brightness: 100 color_temp: 4000 thursday: - from: "17:00:00" to: "23:00:00" data: brightness: 90 color_temp: 3500 friday: - from: "07:00:00" to: "10:00:00" data: brightness: 80 color_temp: 3000 - from: "16:00:00" to: "23:00:00" data: brightness: 60 color_temp: 2500

其中每个顶层键（wednesday、thursday、friday等）对应一周中的某一天，值为时间块列表；每个时间块包含必填的from、to时间，以及可选的data映射。配置项的完整说明如下：

配置键	必填	类型	说明
`schedule`	是	map	schedule 的别名，允许配置多个条目
`name`	是	string	schedule 的友好名称
`icon`	否	icon	前端显示的图标
`monday`~`sunday`	否	list（默认`[]`）	每一天的时间块列表
`from`	是	time	开始时间（激活/开启）
`to`	是	time	结束时间（非激活/关闭）
`data`	否	map（默认`{}`）	时间块激活时附加到实体属性上的键值映射

时间块采用开始时间包含、结束时间排他的边界语义：一个09:00到12:00的时间块从09:00:00.000起激活，直到（但不包括）12:00:00.000。同一天内相邻相接的时间块（如07:00–10:00与10:00–12:00）会平滑过渡，不会在边界处短暂翻转为off；同一天内不允许重叠的时间块，配置校验阶段会被拒绝。这些行为直接影响你读取到的数据在自动化中的语义。

在 UI 中使用 schedule.get_schedule

在自动化或脚本中通过界面添加该动作的步骤如下（出自动作文档）：

进入设置>自动化与场景。
打开现有的自动化或脚本，或选择创建自动化>创建新自动化。
如果是在配置新的自动化，请在When（何时）部分添加触发器。脚本不需要触发器，它们在被其他东西调用时运行。
在Then do（然后执行）部分，选择添加动作。
选择你想要控制的实体。在按目标（参见下文"目标（Targets）详解"）下，选择你想要读取的 schedule。
在该目标显示的动作列表中，选择Schedule: Get schedule。
选择保存。

UI 中的选项

该动作除目标之外没有其他额外选项。

在 YAML 中使用 schedule.get_schedule

在 YAML 中，将该动作引用为schedule.get_schedule，并使用response_variable把结果存入一个变量，以便在后续步骤中使用（示例出自动作文档）：

action: schedule.get_schedule target: entity_id: - schedule.vacuum_robot - schedule.air_purifier response_variable: schedules

这个示例一次性读取了schedule.vacuum_robot和schedule.air_purifier两个计划实体配置的时间范围，并把结果存入名为schedules的响应变量。response_variable的名称可以自行定义，它相当于一个局部变量，作用范围是当前自动化或脚本——只有同一个自动化/脚本中位于该动作之后的步骤才能引用它。

YAML 中的选项

该动作除目标之外没有其他 YAML 选项。

响应数据结构详解

响应中包含你目标中每一个 schedule 实体对应的字段。每个 schedule 有七个字段，对应一周中的每一天（使用小写的英文星期名），字段值为该天配置的时间范围列表；没有配置任何时间块的日期返回空列表。每个时间范围包含一个from时间与一个to时间。

完整的响应示例（出自动作文档）如下：

schedule.vacuum_robot: monday: - from: "09:00:00" to: "15:00:00" tuesday: [] wednesday: [] thursday: - from: "09:00:00" to: "15:00:00" friday: [] saturday: [] sunday: [] schedule.air_purifier: monday: - from: "09:00:00" to: "18:00:00" tuesday: [] wednesday: [] thursday: - from: "09:00:00" to: "18:00:00" friday: [] saturday: - from: "10:30:00" to: "12:00:00" - from: "14:00:00" to: "19:00:00" sunday: []

解读要点：

每个被目标的实体都作为顶层键出现（如schedule.vacuum_robot、schedule.air_purifier）；
每一天的键是小写的英文星期名（monday到sunday），与你界面使用的语言无关；
某天没有任何时间块时，返回[]（空列表）；
同一天可以配置多个时间块（见上例schedule.air_purifier的saturday），它们会按顺序列出；
时间格式为HH:MM:SS字符串，如"09:00:00"。

实战：把今天的计划拼进通知

schedule.get_schedule最常见的用途之一，就是把今天的计划时间动态写入通知。下面是动作文档给出的完整示例：先调用schedule.get_schedule读取计划，再调用notify.nina发送通知，消息中通过模板遍历"今天"对应的时间块：

action: notify.nina data: title: "Today's schedules" message: |- Your vacuum robot will run today: {% set today = now().strftime('%A').lower() %} {% for event in schedules['schedule.vacuum_robot'][today] %} - from {{ event.from }} until {{ event.to }} {% endfor %}

这段模板逐行拆解：

now().strftime('%A').lower()：取当前日期，strftime('%A')输出完整的英文星期名（如Monday），再转小写得到monday，正好与响应数据的星期键一一对应——这也是响应数据固定使用小写英文星期名的原因，方便模板直接索引；
schedules['schedule.vacuum_robot'][today]：从响应变量schedules中取出schedule.vacuum_robot实体、再取出"今天"的时间块列表；
{% for event in ... %}：遍历该列表，用event.from与event.to输出每个时间块的起止时间；
如果今天没有配置任何时间块，for循环不会执行任何迭代，消息中不会出现多余的列表项——这正是"无时间块的日期返回空列表"这一设计带来的便利。

需要说明的是，在文档站源码中该模板片段被{% raw %}标签包裹，以避免 Jekyll 站点构建时把其中的{% set %}、{% for %}当作 Liquid/Jekyll 指令处理；在自动化 YAML 中直接使用上述模板即可，无需 raw 标签。

深入理解 response_variable（动作响应数据）

schedule.get_schedule之所以能"读取并返回配置"，依赖于 Home Assistant 的动作响应数据机制。依据执行动作（Actions）文档：

某些动作会返回可供自动化使用的数据，称为动作响应数据（action response data），典型如calendar.get_events返回未来一段时间的日历事件；
动作通过response_variable指定存放响应数据的变量名，名称可任意定义；
之后在同一个脚本/自动化的后续动作中，即可通过该变量引用返回的数据。

与schedule.get_schedule同类的calendar.get_events示例（出自同一文档）：

action: calendar.get_events target: entity_id: calendar.school data: duration: hours: 24 response_variable: agenda

因此，schedule.get_schedule的调用遵循统一模式：target决定读取哪些实体，response_variable决定结果存放在哪里，之后无论是发通知、写日志还是作为另一个动作的输入，都能直接引用。

目标（Targets）详解

该动作唯一需要配置的就是目标。依据执行动作（Actions）文档的通用目标语法，target是一个映射，至少包含以下键之一（均可传列表，取值应使用小写）：

entity_id：实体 ID 列表，如schedule.vacuum_robot；
device_id：设备 ID 列表；
area_id：区域 ID 列表。

由于schedule.get_schedule允许一次读取多个计划，你可以把同一天内要检查的所有 schedule 实体一次性列在entity_id下（如本文示例中的两个计划），响应数据中会为每个实体各返回一个按星期组织的字段，无需多次调用。

Home Assistant Schedule 集成实战：使用 schedule.get_schedule 动作读取每周时间计划