使用 Home Assistant 的 calendar.get_events 动作读取日历事件并驱动自动化

使用 Home Assistant 的 calendar.get_events 动作读取日历事件并驱动自动化【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iocalendar.get_events是 Home Assistant 内置Calendar日历实体域提供的核心动作action用于在一个日期范围内读取一个或多个日历上的事件例如读出当天的日程、在通知中播报未来 24 小时的安排或把日程数据交给后续自动化步骤处理。本指南以 calendar.get_events 动作文档 为主体结合 Calendar 集成文档 与 动作响应数据处理文档完整覆盖 UI 配置、YAML 编写、参数语义、响应数据结构与实战示例读完后你可以在自动化与脚本中直接、可靠地获取并消费日历事件数据。一、calendar.get_events 是什么用在什么场景Home Assistant 的日历支持面向自动化场景设计无论日历数据实际存储在 CalDAV 服务器、Google Calendar 还是本地文件中只要对应集成提供了日历实体自动化就能读取事件信息。calendar.get_events正是负责读取的动作典型使用场景包括读取当天或未来一段时间的日程拼接成文本发送到手机通知在语音播报如notify或 TTS中读出下一个安排将日程数据暂存到响应变量供同一自动化或脚本的后续步骤继续使用。与 calendar.create_event写入事件不同calendar.get_events只做读取并且会把结果返回到一个响应变量response variable中这一点让它在多步骤流程中特别有用——后续动作可以直接引用查询结果而不必依赖实体状态。在编写自动化时还需要区分两种能力如果只想在事件开始或结束时触发动作应优先使用Calendar 触发器trigger而读取某个时间区间内的所有事件明细则必须用calendar.get_events动作。关于两者的关系与适用场景可参考 Calendar 集成文档 中的 Automation 章节。二、使用前置条件先有日历实体calendar.get_events的动作目标target是日历实体因此使用前需要确保系统中存在可用的日历实体通过 Calendar 集成 接入外部平台例如 CalDAV 服务器对应 caldav 集成使用内置的 Local Calendar 等本地日历方案每个日历在 Home Assistant 中表现为一个独立实体entity形如calendar.school、calendar.family。从 Calendar 集成文档 可以看到日历实体的状态语义为On当前有正在进行的活动事件Off当前没有活动事件Unavailable / Unknown实体不可用或状态未知。需要注意的是实体状态与属性通常只反映下一个事件无法直接用来获取一段时间内的完整日程列表这正是calendar.get_events存在的意义。三、通过 UI 配置该动作在自动化或脚本中通过界面添加动作操作路径如下原文步骤完整保留进入SettingsAutomations scenes。打开现有的自动化或脚本或选择Create automationCreate new automation。如果是新建自动化在When触发部分添加触发器脚本不需要触发器它们由其他动作调用时才运行。在Then do执行部分选择Add action添加动作。选择要控制的对象在By target按目标下选择要读取的日历可多选。在目标对应的动作列表中选择Get calendar events。设置时间范围指定Start time开始时间并选择End time结束时间或Duration持续时间二者之一。选择Save保存。UI 中的选项选项说明是否必填Start time返回该时间之后的事件不设置时默认从当前时间开始否End time返回该时间之前的事件结束时间不包含exclusive不能与持续时间同时使用否Duration从开始时间起返回该持续时间范围内的事件不能与结束时间同时使用否四、通过 YAML 配置完整示例与参数说明在 YAML自动化或脚本中动作名称为calendar.get_events。因为该动作会返回数据必须通过response_variable把结果存入一个命名变量供后续步骤使用。原文示例多日历 时长查询action: calendar.get_events target: entity_id: - calendar.school - calendar.work data: duration: hours: 24 response_variable: agenda该示例会读取calendar.school与calendar.work未来 24 小时内的事件并把结果保存到名为agenda的响应变量中。response_variable的名称可自由定义——动作响应数据处理文档 明确指出它是存放响应数据的变量variable你可以任意命名。YAML 参数一览参数类型说明是否必填start_date_timestring返回该时间之后的事件例如2024-03-10 20:00:00不设置时默认为当前时间否end_date_timestring返回该时间之前的事件不包含该时刻例如2024-03-10 23:00:00不能与duration同时使用否durationmap从开始时间起返回该时长范围内的事件例如hours: 24不能与end_date_time同时使用否response_variablestring存放响应数据的变量名供同一自动化或脚本的后续动作引用是返回型动作必需时间范围设置的核心规则用开始时间 结束时间或用开始时间 持续时间二选一结束时间与持续时间不能同时出现。五、响应数据结构详解calendar.get_events按目标日历返回结果响应以日历实体 ID 为键每个日历对应一个events列表列表中的每个事件包含以下字段字段说明summary事件的标题description事件的更详细描述如有start事件的开始日期或日期加时间end事件的结束日期或日期加时间结束时间不包含exclusivelocation事件的地点如有原文给出的响应示例已缩写calendar.school: events: - summary: Parents evening start: 2024-03-10 19:00:00 end: 2024-03-10 20:00:00 location: Main hall calendar.work: events: - summary: Team standup start: 2024-03-10 09:00:00 end: 2024-03-10 09:15:00理解这个结构很重要顶层是日历 ID其下是events数组。后续步骤在模板中引用时需要通过日历 ID 这一层去访问事件列表。六、实战把日程结果用于通知与模板动作响应数据处理文档 给出了一个完整的查询日程 → 发送通知示例说明响应变量如何被后续动作消费。先执行查询并把结果存入agendaaction: calendar.get_events target: entity_id: calendar.school data: duration: hours: 24 response_variable: agenda然后在同一脚本/自动化的后续动作中用模板遍历agenda中的事件并发送通知action: notify.gmail_com data: target: gduser1workspacesamples.dev title: Daily agenda for {{ now().date() }} message: - Your agenda for today: p {% for event in agenda[calendar.school].events %} {{ event.start}}: {{ event.summary }}br {% endfor %} /p关键写法说明通过agenda[calendar.school].events访问指定日历的事件列表即响应结构中的以日历 ID 为键一层每个event对象可直接访问event.summary、event.start、event.end、event.location、event.description等字段通知消息能使用的字段取决于通知类型的支持情况具体以所用通知服务的文档为准。七、与日历触发器、事件写入的配合calendar.get_events常常与 Calendar 生态的其他能力配合使用构成完整的日历自动化方案事件触发若只需在事件开始/结束时执行动作使用 Calendar 触发器 更合适例如automation: - triggers: - trigger: calendar event: start entity_id: calendar.personal offset: -00:15:00注意 Calendar 集成文档 的提示日历约每 15 分钟读取一次测试时不要把事件安排在距当前时间不足 15 分钟内否则触发器可能不触发同时应避免使用single模式改用queued或parallel以支持同时开始的多个事件。事件写入需要把信息记录到日历时使用calendar.create_event例如记录洗衣机完成的日志两者常组合用于读取既有日程 写入新安排的完整工作流详见 create_event 动作文档。八、注意事项与最佳实践时间范围二选一end_date_time与duration互斥同时设置会导致配置无效。结束时间不包含end_date_time表示该时刻之前事件恰好在此刻结束时不包含在内这与calendar.create_event中事件结束时间排他的语义一致。响应变量必须命名calendar.get_events的返回值依赖response_variable保存漏写则无法在后续步骤引用结果。结果为只读快照响应数据是查询时刻的日程快照适合通知、播报、记录等场景若需持续监听事件变化应改用日历触发器。多日历聚合target.entity_id可一次指定多个日历响应会按日历 ID 分别给出events方便在模板中按需取用。通过上述配置方法与响应数据处理技巧你可以在不依赖外部脚本的情况下用纯 Home Assistant 的自动化/脚本能力完成定时读取日程、按需播报安排、记录事件历史等典型日历自动化需求。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考