第1章 用 YAML 编写 Home Assistant 自动化
第 1 章:使用 YAML 编写自动化
Home Assistant 中的自动化通常通过界面创建,但存储为 YAML。YAML 是一种人类可读的数据序列化语言,用于以结构化格式存储和传输数据。在 Home Assistant 中,YAML 常用于配置文件,例如 configuration.yaml 或 automations.yaml。[了解更多]。若要编辑自动化的 YAML,请选择该自动化,点击右上角的菜单按钮,然后选择“在 YAML 中编辑”。
界面会将自动化写入 automations.yaml。该文件由界面管理,请勿手动编辑。
你也可以在 configuration.yaml 或其他 YAML 文件中直接编写自动化。configuration.yaml 是 Home Assistant 的主配置文件,列出了要加载的集成及其配置。某些情况下需手动编辑该文件,但大多数集成可通过界面配置。[了解更多]。要在 configuration.yaml 中添加带标签的自动化块,示例如下: # UI 运行所需的配置 automation: !include automations.yaml
# 带标签的自动化块 automation kitchen: - triggers: - trigger: ...
你可以添加任意数量的带标签自动化块。
修改 YAML 文件中的自动化后,请重新加载它们。具体步骤参见“重新加载自动化”。
配置变量
找不到你的配置文件?
alias 字符串 (可选)
自动化的名称。
id 字符串 (可选)
自动化的唯一 ID。有了 ID,你可以在界面中更改名称和实体 ID,自动化还会存储调试跟踪记录。ID 必须是文本。若需使用数字,请将其放在引号中,例如 id: "1700000000000"。
description 字符串 (可选)
自动化的描述。
initial_state 布尔值 (可选)
用于定义自动化启动时的状态。若未设置,状态将从上次运行中恢复。若无可恢复的状态,则自动化默认开启。参见“自动化初始状态”。
默认值:从上次运行恢复,否则为 true
trace 映射 (可选,默认:{})
用于配置存储的跟踪记录,目前仅可配置 stored_traces。
stored_traces 整数 (可选,默认:5)
要存储的跟踪记录数量。参见“存储的调试跟踪记录数量”。
variables 映射 (可选,默认:{})
在条件和操作模板中可用的变量。
参数名 任意值
变量的值。任意有效的 YAML 均可。也可使用模板为变量传值。
trigger_variables 映射 (可选,默认:{})
可在所有触发器模板中使用的变量,例如在模板触发器、触发器的 enabled 选项、事件触发器的 event_type、Webhook 触发器的 webhook_id 或 MQTT 触发器的 topic 中。Home Assistant 在设置触发器时(如加载自动化或开启自动化时)会设置这些变量。
参数名 任意值
变量的值。任意有效的 YAML 均可。仅支持受限模板。
mode 字符串 (可选,默认:single)
控制当自动化仍在执行时再次被调用会发生什么。参见“自动化模式”。
max 整数 (可选,默认:10)
控制同时执行和/或排队的最大运行次数。仅适用于 queued 和 parallel 模式。最小值为 2。
max_exceeded 字符串 (可选,默认:warning)
当超过 max 值时(在 single 模式下实际为 1),会输出日志消息。此选项控制该日志消息的严重级别。参见“日志级别”获取有效选项列表。也可设置为 silent 以抑制消息输出。
triggers 列表 必需
启动自动化的触发器。可添加多个触发器,当其中任何一个触发时,自动化即启动。
alias 字符串 (可选)
触发器的名称。显示在自动化编辑器和跟踪记录中。
id 字符串 (可选)
用于在自动化中确定是哪个触发器启动了自动化的 ID。ID 必须是文本。若需使用数字,请将其放在引号中。
enabled 布尔值 | 模板 (可选,默认:true)
设置为 false 可禁用触发器。也可使用受限模板。详情参见“禁用触发器”。
variables 映射 (可选,默认:{})
在条件和操作序列中可用的变量。
参数名 任意值
变量的值。任意有效的 YAML 均可。也可使用模板为变量传值。
conditions 列表 (可选)
自动化执行操作前必须为真的条件。当触发器启动自动化时,Home Assistant 会检查条件。若条件不满足,自动化将停止。默认情况下,列出的所有条件都必须为真。要更改此行为,请使用 And、Or 和 Not 条件。
actions 列表 必需
自动化中要执行的操作序列。
YAML 示例
一个基于 YAML 的自动化示例,可添加到 configuration.yaml。 # configuration.yaml 中的条目示例 automation my_lights: # 日落前 1 小时若有人在家则开灯 # 若有人在 16:00-23:00 之间到家则开灯 - alias: "规则 1 晚间开灯" triggers: # 每个触发器配置的第一行前加 '-' 以输入多个 - trigger: sun event: sunset offset: "-01:00:00" - trigger: state entity_id: - person.paulus - person.anne_therese to: "home" conditions: # 每个条件配置的第一行前加 '-' 以输入多个 - condition: state entity_id: - person.paulus - person.anne_therese match: any state: "home" - condition: time after: "16:00:00" before: "23:00:00" actions: # 单个操作项前无需 '-',但也可以加 - action: homeassistant.turn_on target: entity_id: light.living_room
# 所有人离开家时关灯 - alias: "规则 2 - 离家模式" triggers: - trigger: state entity_id: zone.home to: "0" actions: - action: light.turn_off target: entity_id: all
# 晚上 Paulus 离家时发送通知 - alias: "离家通知" triggers: - trigger: zone event: leave zone: zone.home entity_id: device_tracker.paulus conditions: - condition: time after: "20:00" actions: - action: notify.notify data: message: "Paulus 离开了家"
# 通过 Pushover 发送小米魔方的事件通知。小米集成自定义事件。 - alias: "小米魔方操作" initial_state: false triggers: - trigger: event event_type: cube_action event_data: entity_id: binary_sensor.cube_158d000103a3de actions: - action: notify.pushover data: title: "检测到魔方事件" message: "魔方触发了此事件:{{ trigger.event }}"
旧版 YAML 语法
旧示例(如论坛帖子、指南或蓝图)可能使用了已更名的键。Home Assistant 仍接受旧键,因此这些示例保持可用。在编辑器中保存自动化时,Home Assistant 会将键更改为当前名称。
已更名的键包括:
操作中的 service: 现更名为 action:。
在 Home Assistant 2024.8 中更名。
触发器中的 platform: 现更名为 trigger:。
在 Home Assistant 2024.10 中更名。
自动化的顶层 trigger:、condition: 和 action: 键现更名为 triggers:、conditions: 和 actions:。
在 Home Assistant 2024.10 中更名。
在自动化级别,triggers:、conditions: 和 actions: 为复数。在这些列表中识别触发器或条件的键保持单数(trigger: 或 condition:),而操作调用使用单数 action:。
在同一位置使用旧键或新键,不可混用。例如,自动化不能同时包含 trigger: 和 triggers:。在将旧示例的部分内容复制到自动化之前,请将其键更改为当前名称。
额外选项
某些选项仅在直接通过 YAML 编写自动化时可用,无法通过用户界面配置。
自动化初始状态
启动时,自动化默认恢复 Home Assistant 运行结束时的最后状态。这可由 initial_state 选项控制。设为 false 或 true 可强制初始状态为关或开。 automation: - alias: "自动化名称" initial_state: false triggers: - trigger: ...
存储的调试跟踪记录数量
使用 YAML 时,你可以配置自动化存储的调试跟踪记录数量。这由 trace 下的 stored_traces 选项控制。将 stored_traces 设置为你希望存储的跟踪记录数量。若未指定,默认值为 5。 automation: - alias: "自动化名称" trace: stored_traces: 10 triggers: - trigger: ...
将 YAML 自动化迁移到 automations.yaml
若要迁移手动编写的自动化以使用编辑器,需将其复制到 automations.yaml。确保 automations.yaml 保持为列表!每复制一个自动化,都必须添加一个 id。只要是唯一的字符串即可。 # automations.yaml 条目示例。注意,automations.yaml 始终是列表! - id: my_unique_id # <-- 编辑器运行必需,使用编辑器创建的自动化会自动生成 id alias: "Hello world" triggers: - trigger: state entity_id: sun.sun from: below_horizon to: above_horizon conditions: - condition: numeric_state entity_id: sensor.temperature above: 17 below: 25 value_template: "{{ float(state.state) + 2 }}" actions: - action: light.turn_on
从 YAML 文件中删除自动化
若要删除在界面中管理的自动化,请使用自动化编辑器。步骤参见“复制、关闭或删除自动化”。
删除自动化前,请检查是否有其他自动化、脚本或仪表盘使用了它。
要删除通过 YAML 编写的自动化:
打开包含该自动化的 YAML 文件,例如 configuration.yaml。关于如何设置文件访问和编辑器,参见“编辑 configuration.yaml”。
若自动化在 automations.yaml 中且有 id,请在自动化编辑器中删除。
删除整个自动化。它始于以 - 开头的行,例如 - id:、- alias: 或 - triggers:。止于下一个相同缩进且以 - 开头的行之前。
若使用 !include_dir_list 将自动化拆分为每个文件一个自动化,则文件仅包含此自动化,且开头无 -。请删除整个文件。
检查配置,然后重新加载自动化。
结果:自动化被移除。若其曾有 id,实体将保留,直到你删除它。
若自动化曾有 id,请删除其实体:
前往 设置 > 设备与服务 > 实体。 选择 进入选择模式,然后选择该自动化。 选择三点菜单,然后选择 删除所选。确认删除。
重新加载自动化
修改 YAML 文件中的自动化后,重新加载以应用更改。重新加载仅影响你修改的自动化:
若其中一个正在运行,该运行将停止。 若其中一个有正在进行的“至少持续”时间,该持续时间将丢失。
详情参见“运行未完成时停止的情况”。
前往 设置 > 工具 > YAML。 在 YAML 配置重新加载下,选择 自动化。
若要在自动化或脚本中重新加载自动化,请使用 重新加载自动化 操作。
帮助我们改进文档
此页面对你有帮助吗?
建议编辑此页面,或查看/提供此页面的反馈。
编辑 提供反馈 查看已提供的反馈