Home Assistant NWSnws.get_forecasts_extra动作指南获取美国国家气象服务扩展预报数据【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇文章围绕 Home Assistant 中 National Weather ServiceNWS集成提供的Get extra forecasts datanws.get_forecasts_extra动作展开讲解它相比标准weather.get_forecasts动作补充了哪些数据如何在自动化与脚本中通过 UI 或 YAML 调用它以及如何利用response_variable捕获并消费返回的short_description、detailed_description等字段。读完本文你将掌握一条完整、可直接落地的抓取美国国家气象服务文字化天气预报的实战链路。背景为什么需要nws.get_forecasts_extraNWS 集成 使用美国国家气象服务National Weather Service的 Web API 作为气象数据源为你的位置提供逐小时hourly与日/夜twice daily两种粒度的预报。默认情况下集成通过标准weather.get_forecasts动作返回以结构化字段如condition、temperature、precipitation_probability为主的预报数据。但结构化字段无法表达预报员撰写的自然语言描述。从 Home Assistant 2024.8 版本开始NWS 天气实体的weather.get_forecasts返回结果中不再包含detailed_description字段取而代之的是新增的nws.get_forecasts_extra动作来专门提供这类额外数据。正如仓库发布日志 source/_posts/2024-08-07-release-20248.markdown 所述NWS weather entities no longer have adetailed_descriptionin the return from theweather.get_forecastsservice. A new service,nws.get_forecasts_extra, is provided that includesdetailed_description.因此如果你需要在自动化或脚本中展示 NWS 的文字化天气预报例如一句50% chance of rain, otherwise partly cloudy with a high of 75°F.nws.get_forecasts_extra就是官方指定的获取途径。该动作的定义位于 source/_actions/nws.get_forecasts_extra.markdowndomain 为nws目标实体为 weather 类型。动作的目标Targetsnws.get_forecasts_extra是一个**需要指定目标target**的动作。目标决定了动作作用于哪些 weather 实体支持的指向方式依据 source/_includes/actions/targets.md如下实体Entity单个具体的 weather 实体例如weather.khou。设备Device该设备所属的全部 weather 实体。区域Area该房间/区域内的全部 weather 实体。楼层Floor该楼层上的全部 weather 实体。标签Label共享该标签的全部 weather 实体。同一个动作中可以同时指定不同类型的多个目标例如同时传入一个具体实体和一个区域动作会同时对它们执行。从用户界面使用该动作如果你更喜欢可视化构建自动化与脚本可以在 UI 中按向导逐步完成无需编写 YAML。具体步骤为进入SettingsAutomations scenes。打开一个已有的自动化或脚本如果是新建选择Create automationCreate new automation。新建自动化时在When当……时部分添加一个触发器。脚本不需要触发器它们由其他自动化或调用方触发运行。在Then do然后执行部分选择Add action。在搜索框中搜索并选择National Weather Service (NWS): Get extra forecasts data。选择 weather 实体作为目标然后选择Forecast type。点击Save保存。UI 中的选项选项说明必填Forecast type预报的范围hourly逐小时或twice_daily一天两次即日/夜。是由于该动作会返回数据在 UI 中配置时同样需要通过response_variable之类的机制捕获返回结果详见下文捕获响应数据部分。从 YAML 使用该动作在 YAML 中该动作以nws.get_forecasts_extra引用。因为它会返回数据必须使用response_variable捕获结果。一个最基础的自动化/脚本动作示例如下action: nws.get_forecasts_extra target: entity_id: weather.khou data: type: twice_daily response_variable: weather_forecast执行后额外预报数据会被存入weather_forecast变量供后续动作通过模板访问。YAML 选项选项必填类型说明type是string预报范围取值为hourly或twice_daily。需要特别说明的是type字段的两种取值对应 NWS API 的两种预报端点hourly逐小时预报。依据发布日志 source/_posts/2024-08-07-release-20248.markdown 与动作文档detailed_description不再在hourly预报中提供上游 API 不返回该数据但short_description可用。twice_daily一天两次的日/夜预报包含detailed_description、short_description与is_daytime字段。捕获响应数据response_variable凡返回数据的动作都应当通过response_variable捕获其响应。Home Assistant 会把响应数据以变量形式保存之后在同一自动化或脚本中即可用模板读取。结合模板传感器使用该类响应数据是常见模式——仓库在 source/_integrations/weather.markdown 中给出了一个使用weather.get_forecastsresponse_variable的模板传感器示例其用法对nws.get_forecasts_extra同样适用template: - triggers: - trigger: time_pattern hours: /1 actions: - action: nws.get_forecasts_extra data: type: hourly target: entity_id: weather.khou response_variable: forecast_extra sensor: - name: NWS short description unique_id: nws_short_description state: {{ forecast_extra[weather.khou].forecast[0].short_description }}这样每次触发时动作重新拉取预报并刷新模板传感器的状态即可把 NWS 的文字化预报暴露为一个普通传感器供仪表盘、通知等消费。响应数据Response data结构该动作的响应是一个以目标 weather 实体为键的映射mapping每个实体下包含一个forecast字段forecast是一个按时间排列的预报条目列表。每个条目可能包含以下字段字段说明datetime该条预报条件的开始时间。short_description天气状况的简短文字描述。is_daytime该预报时段是否处于白天。仅twice_daily预报会设置此字段。detailed_description详细、自然语言化的预报描述。仅twice_daily预报会设置此字段。对于twice_daily预报响应形如weather.khou: forecast: - datetime: 2023-02-17T14:00:0000:00 is_daytime: true detailed_description: - 50% chance of rain, otherwise partly cloudy with a high of 75°F. short_description: Partly sunny then slight chance showers and thunderstorms将detailed_description与标准weather.get_forecasts的响应对比即可看到差异标准预报响应见 source/_integrations/weather.markdown 中的示例以condition、precipitation_probability、temperature等数值/枚举字段为主不包含自然语言描述而nws.get_forecasts_extra补上的正是short_description与detailed_description这类可直接朗读或展示的文本字段。实战示例把 NWS 文字预报用进通知将以上要素组合起来一个典型场景是夜间定时拉取日/夜预报把详细的文字化预报通过通知发送到手机。例如alias: Send NWS forecast summary triggers: - trigger: time at: 06:30:00 conditions: [] actions: - action: nws.get_forecasts_extra target: entity_id: weather.khou data: type: twice_daily response_variable: forecast_extra - action: notify.mobile_app_phone data: title: 今日天气预报 message: {{ forecast_extra[weather.khou].forecast[0].detailed_description }} mode: single该示例完整呈现了触发 → 调用动作 → 捕获响应 → 消费响应的调用链先按既定时刻触发用twice_daily获取包含detailed_description的预报再将其作为通知正文发出。注意事项与限制nws.get_forecasts_extra的目标必须为 weather 实体。仓库变更记录 source/changelogs/core-2024.8.markdown 中提及Restrict nws.get_forecasts_extra selector to nws weather entities即在 UI 中该动作的实体选择器被限定为 NWS weather 实体实际指向的实体应是 NWS 集成创建的 weather 实体例如weather.khou。hourly预报不含detailed_description因为 NWS 上游 API 对该端点不返回该数据如需文字化详细描述请使用twice_daily。访问返回数据时注意forecast是列表forecast[0]是最近的一条预报datetime字段表示该条预报的开始时间可用作匹配判断。若在配置 NWS 集成时未指定 METAR 站代码系统会自动选择距离所配置经纬度最近的站点站点列表会以DEBUG级别打印到日志中详见 source/_integrations/nws.markdown这有助于排查预报数据来源异常。相关阅读NWS 集成文档配置方法、API 说明与数据来源底层使用 pynws 库拉取数据。Weather 集成文档标准weather.get_forecasts动作、天气实体状态与属性定义。Home Assistant 2024.8 发布说明nws.get_forecasts_extra引入的背景与detailed_description字段的迁移说明。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考