Home Assistant 的 OpenWeatherMap 分钟级降水预报 Action 实战指南-迪斯科星球

Home Assistant 的 OpenWeatherMap 分钟级降水预报 Action 实战指南

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

本文以 Home Assistant 官方文档仓库中的source/_actions/openweathermap.get_minute_forecast.markdown为核心，系统讲解openweathermap.get_minute_forecast动作（action）的调用前提、UI 与 YAML 两种配置方式、响应数据结构，并结合仓库内脚本与自动化文档给出模板化消费响应数据的完整示例。读完本文，你可以在自动化或脚本中按分钟读取未来一小时内降水预报，实现"雨前自动关窗""浇灌决策""出门带伞提醒"等实战场景。

这个动作解决什么问题

openweathermap.get_minute_forecast用于从 OpenWeatherMap 获取未来一小时逐分钟的降水（雨或雪）预报。它的典型应用包括：

决定是否启动花园洒水器（例如未来 60 分钟内有降水就跳过浇灌）；
在降雨到达前给自己发送提醒（例如提前通知收衣服、关窗户）；
为后续自动化提供逐分钟降水趋势判断依据。

该动作通过响应数据（response data）返回结果，返回值为未来 60 分钟内每一分钟的预报降水或降雪量，适合结合模板处理响应数据使用。

调用前提：集成模式必须为 v3.0

{% important %} 分钟级预报仅在 OpenWeatherMap 集成的模式（mode）设置为v3.0时可用。若集成模式为current、forecast或air_pollution，调用该动作会失败。 {% endimportant %}

OpenWeatherMap 集成支持两类服务与多种模式，详见集成文档：

One Call API 3.0：模式v3.0，提供当前天气、48 小时逐小时预报与 8 天逐日预报，是唯一支持分钟级预报的模式；
Free 服务：模式current（仅当前天气）、forecast（每 3 小时一步、共 5 天预报）、air_pollution（当前空气质量），均不提供分钟级预报。

因此在使用本动作前，请先在 OpenWeatherMap 网站上激活 One Call API 3.0 订阅（免费额度为每天 1000 次调用，可在 Billing plans 页面设置每日调用上限以避免超量计费），然后在 Home Assistant 的集成配置中选择模式v3.0。需要注意：新注册的 API Key 激活可能需要 10 分钟到 2 小时，且订阅激活最长可能需要 2 小时；如果 API Key 与所选服务不匹配（One Call 3.0 与 Free 混用），会报 Invalid API-key 错误。

通过 UI 调用该动作

如果你习惯可视化地创建自动化或脚本，Home Assistant 会逐步引导你完成该动作的配置，无需编写 YAML。具体步骤如下：

进入设置>自动化与场景（Automations & scenes）；
打开一个已有的自动化或脚本，或选择创建自动化>创建新自动化；
若是新建自动化，在When（触发条件）部分添加触发器；脚本不需要触发器，它们在被其他流程调用时运行；
在Then do（执行动作）部分选择添加动作；
在搜索框中搜索并选择OpenWeatherMap: Get minute forecast；
选择要获取预报的 OpenWeatherMap 天气实体（weather entity）；
在Response variable（响应变量）字段中填写一个名称用于存储返回数据，例如weather_forecast；
点击保存。

该动作在 UI 中除了目标（target）之外没有任何其他可配置选项。

在 YAML 中调用该动作

在自动化或脚本的 YAML 中，动作名称为openweathermap.get_minute_forecast。因为它会返回数据，所以需要将结果存入响应变量（response variable）。基本示例：

action: | action: openweathermap.get_minute_forecast target: entity_id: weather.openweathermap response_variable: weather_forecast

该动作在 YAML 中同样没有目标之外的任何选项。关于响应变量的通用机制，参见脚本文档中的变量与使用模板处理响应数据：response_variable可以自定义任意名称，存储的数据可在同一脚本的后续动作中通过模板读取。

动作的目标（Target）

该动作必须指定目标。目标可以指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标覆盖到的每一个 weather 实体执行该动作：

实体（Entity）：某个具体的 weather 实体，如weather.openweathermap；
设备（Device）：属于某设备的所有 weather 实体；
区域（Area）：某个房间或区域内的所有 weather 实体；
楼层（Floor）：某个楼层上的所有 weather 实体；
标签（Label）：共享某个标签的所有 weather 实体。

你也可以在同一个动作中混合选择不同类型的目标，例如同时指定一个具体实体和一个区域，动作会同时作用于两者。

响应数据结构

动作会为每个被目标选中的 weather 实体返回预报数据，返回结果以实体 ID 作为键。每个实体下包含一个forecast字段，它是一个包含60 个条目的列表，对应未来一小时的每一分钟。每个条目包含两个字段：

字段	含义
`datetime`	该预报条件对应的时间（ISO 8601 格式）
`precipitation`	预报降水量，单位毫米/小时（mm/h）

一个精简后的响应示例：

weather.openweathermap: forecast: - datetime: "2024-10-19T18:59:00+00:00" precipitation: 5.46 - datetime: "2024-10-19T19:00:00+00:00" precipitation: 5.62 - datetime: "2024-10-19T19:01:00+00:00" precipitation: 5.62

在脚本中消费响应数据

仓库中的动作文档将"使用模板处理响应数据"作为通用机制（见 source/_docs/scripts/perform-actions.markdown）：响应数据适合存放动态的、体量较大的数据（比如接下来一周的日历事件或详细的行车路线），这类数据不适合放进实体状态。

下面是一个把分钟级预报与通知动作组合起来的完整示例：先调用动作把结果存入weather_forecast，再通过模板遍历forecast列表，判断未来 30 分钟内是否有降水，若有则发送通知提醒。

sequence: - action: openweathermap.get_minute_forecast target: entity_id: weather.openweathermap response_variable: weather_forecast - action: notify.mobile_app_phone data: title: "未来 30 分钟降水提醒" message: >- {% set minutes = weather_forecast['weather.openweathermap'].forecast[:30] %} {% set raining = minutes | selectattr('precipitation', 'gt', 0) | list %} {% if raining %} 未来 30 分钟内有降水，最大强度约 {{ (raining | map(attribute='precipitation') | max) | round(1) }} mm/h。 {% else %} 未来 30 分钟预计无降水。 {% endif %}

说明：上述模板仅为演示响应数据的一种消费方式。实际字段可用的模板函数以 Home Assistant 官方模板文档为准，具体通知方式取决于你所使用的 notify 服务类型。

使用须知（Good to know）

预报覆盖未来 60 分钟，每分钟一个条目；
precipitation值为0表示该分钟预计无雨或无雪；
预报的准确性取决于 OpenWeatherMap 针对你所在位置提供的数据质量——它只提供数据源的预报能力，不保证绝对精确。

立即动手测试

想不写 YAML 就验证效果？打开设置>工具>动作（Actions），搜索openweathermap.get_minute_forecast，填入目标实体并点击执行动作，即可在真实实体上看到返回的响应数据，确认你的集成模式与目标实体配置是否正确。

企业官网建设流程全解析