企业官网建设流程全解析

Home Assistant 实战：使用 amberelectric.get_forecasts 获取 Amber Electric 电价预测并自动调度家电

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

Amber Electric（澳大利亚电力零售商）向用户提供批发市场的实时电价与预测数据，其 Home Assistant 集成不仅暴露了价格、预测、描述符等传感器，还通过amberelectric.get_forecasts这一 action 让你在自动化与脚本中按需拉取某一站点的价格预测，并将结果存入响应变量供后续步骤使用。本文以官方文档 source/_actions/amberelectric.get_forecasts.markdown 为主体，结合集成文档 source/_integrations/amberelectric.markdown，完整讲解该 action 的 UI 与 YAML 两种用法、全部参数与响应字段，并给出"在最低价时段自动启动电器"的实战方案。

一、先理解背景：Amber Electric 的三个电价通道

在调用amberelectric.get_forecasts之前，需要先理解 Amber Electric 的价格体系。根据集成文档，价格被划分为三种 channel（通道）类型：

• general：记录灯光、电器等所有常规用电的通道；
• controlled_load（受控负载）：仅在非高峰时段激活的特殊通道，电热水系统常接入该通道；
• feed_in（馈电）：记录太阳能板与电池向电网输出的通道。

该集成会为每个通道类型暴露价格（Price，$/kWh）、预测（Forecast，未来 12 小时）与描述符（Descriptor）传感器，另有电价尖峰二进制传感器与可再生能源占比传感器。get_forecastsaction 正是让你按站点、按通道显式拉取这些预测数据，而不是被动等待传感器更新。

从仓库的 changelog 可以确认该 action 的演进轨迹：

• source/changelogs/core-2025.8.markdown：Add forecast service to amberelectric（由 @madpilot 提交，PR #144848）——即本 action 的引入版本；
• source/changelogs/core-2025.12.markdown 与 source/changelogs/core-2026.3.markdown：后续对服务注册方式与 config entry 提取方式的内部重构，不影响对外调用参数。

二、在 UI 中调用该 action（可视化方式）

amberelectric.get_forecasts与其他 action 一样，支持完全通过 UI 搭建，无需编写 YAML（详见 source/_includes/actions/ui_header.md）。操作步骤如下：

1. 进入设置 > 自动化与场景（Settings > Automations & scenes）；
2. 打开一个已有的自动化或脚本，或者选择创建自动化 > 创建新自动化（Create automation > Create new automation）；
3. 如果新建的是自动化，先在When（触发条件）部分添加一个触发器；脚本则不需要触发器，它由其他对象调用时才会运行；
4. 在Then do（执行动作）部分选择添加动作（Add action）；
5. 在搜索框中搜索并选择Amber Electric: Get price forecasts；
6. 为配置条目（Config entry）选择站点，并选择要获取的通道类型（Channel type）；
7. 点击保存（Save）。

需要注意：该 action 不支持 targets（目标对象）。在 UI 中，你不会被提示选择区域、设备、实体或标签。这也符合其语义——它面向"站点级电价数据"，而非某个具体实体。

UI 中的选项（Options in the UI）

三、在 YAML 中调用：参数与响应变量

如果你直接编写 YAML，或者想了解 Home Assistant 在底层究竟做了什么，可以参考 source/_includes/actions/yaml_header.md 中的技术参考。在 YAML 中，该 action 的完整名称是amberelectric.get_forecasts，结果必须存入一个响应变量（response variable），以便在自动化或脚本的后续步骤中使用。

官方文档给出的基础示例：

action: | action: amberelectric.get_forecasts data: config_entry_id: 6b4be47a1fa7c3764f14cf756dc9899d channel_type: general response_variable: forecasts

这段配置的作用是：获取站点6b4be47a1fa7c3764f14cf756dc9899d的 general 通道价格预测，并将结果存入名为forecasts的响应变量。注意示例中的config_entry_id是占位符，实际使用时需替换为你自己站点的配置条目 ID（可在设置 > 设备与服务中查看对应条目的 ID）。

YAML 参数详解（Options in YAML）

需要特别留意的是channel_type在 YAML 中的取值使用下划线：controlled_load与feed_in，而在 UI 中则显示为controlled load与feed-in。这也是最容易踩坑的地方——直接照抄 UI 中的写法到 YAML 会导致参数校验失败。

四、响应数据结构：每一个预测区间字段详解

调用成功后，响应包含一个forecasts列表，其中每个预测区间包含以下字段：

官方文档给出的缩短版响应示例：

forecasts: - duration: 30 date: "2024-01-01" nem_date: "2024-01-01T12:30:00+10:00" per_kwh: 0.08 spot_per_kwh: 0.04 start_time: "2024-01-01T12:00:00+10:00" end_time: "2024-01-01T12:30:00+10:00" renewables: 45 spike_status: "none" descriptor: "low"

关于descriptor的取值，集成文档给出了完整集合：extremely_low、very_low、low、neutral、high和spike。集成同时提供一个"电价尖峰"二进制传感器，当当前价格超过 $3/kWh 时触发，可与spike_status字段互相印证。

五、实战示例：在一天中电价最低的时段启动洗衣机

文档明确指出该 action 的核心价值："例如在预测的最便宜时段启动电器"。下面是一个完整的 YAML 自动化示例，演示如何将响应变量与后续步骤串联——这比单次调用更能体现 response variable 的实战意义。

假设你在夜间电价低时运行洗衣机，可以编写如下自动化（config_entry_id需替换为实际值）：

alias: "Run washing machine at cheapest hour" trigger: - platform: time at: "23:30:00" action: - action: amberelectric.get_forecasts data: config_entry_id: 6b4be47a1fa7c3764f14cf756dc9899d channel_type: general response_variable: forecasts - variables: cheapest: >- {{ forecasts.forecasts | selectattr('descriptor', 'eq', 'low') | sort(attribute='per_kwh') | first }} - delay: hours: "{{ cheapest.start_time | as_timestamp | timestamp_local }}" # 此处按需插入"启动洗衣机"的动作 - action: switch.turn_on target: entity_id: switch.washing_machine

这个示例展示了 response variable 的典型用法：先调用 action 拿到完整的forecasts列表，再通过 Jinja 模板在后续步骤中筛选、排序并定位最优区间，进而控制设备。你可以依据同样的思路结合renewables字段（可再生能源占比）来选择"既便宜又绿色"的时段，或结合spike_status避开尖峰时段。

六、自行验证：在开发者工具中测试

如果你不想直接修改自动化，可以先用开发者工具做一次"零代码"验证（见 source/_includes/actions/try_it.md）：

1. 打开设置 > 工具 > 操作（Settings > Tools > Actions）；
2. 搜索amberelectric.get_forecasts；
3. 填写配置条目与通道类型；
4. 点击执行操作（Perform action）。

你会立即看到返回的forecasts列表与真实实体状态，无需编写任何 YAML 即可确认参数与响应是否符合预期。若遇到问题，可携带 action 名称与期望结果前往 Home Assistant 社区求助（source/_includes/actions/stuck.md 提供了 Discord、官方论坛与 subreddit 等渠道）。

七、关键要点速查

• action 名称：amberelectric.get_forecasts（UI 显示为 "Amber Electric: Get price forecasts"）。
• 必填参数：config_entry_id（站点配置条目）与channel_type（通道类型）。
• 通道枚举：YAML 中使用general、controlled_load、feed_in（下划线形式）；UI 中显示为general、controlled load、feed-in。
• 不支持 targets：不会提示选择区域、设备、实体或标签。
• 结果必须存入响应变量：通过response_variable: forecasts供后续步骤使用。
• 响应核心字段：per_kwh（预测电价）、spot_per_kwh（现货价）、start_time/end_time（区间起止）、renewables（可再生占比）、spike_status（尖峰状态）、descriptor（价格描述）。
• 可用版本：该 action 自 2025.8 版本（PR #144848）引入，后续版本仅涉及内部实现重构，调用方式保持稳定。

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