Home Assistant homeassistant.update_entity 动作实战指南强制实体立即刷新数据【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 官方文档home-assistant.io 仓库中的 Update entity 动作文档 为主体完整讲解homeassistant.update_entity动作的用途、UI 操作步骤与 YAML 调用方式并结合仓库内的通用任务文档与文档站渲染插件补充该动作的边界条件如 10 秒防抖、仅支持按实体定向及其在自定义轮询自动化中的典型用法。读完后你将能够在自动化或脚本中精确控制某个传感器在任意时刻强制刷新一次读数并理解它不会改变实体自身更新节奏这一关键语义。这个动作解决什么问题homeassistant.update_entity是 Home Assistant 核心homeassistant域提供的动作其官方描述为Forces one or more entities to refresh their data right away强制一个或多个实体立即刷新其数据。典型的适用场景是某个传感器每几分钟才轮询一次数据而你在自动化里恰好要读取它的值。此时可以调用该动作强制实体马上更新避免自动化读到过期数据。原文档给出了明确的语义边界它只是请求实体现在就更新一次不会改变该实体自身按什么节奏更新normal update schedule continues unchanged。有些实体不按计划轮询数据例如仅在被推送时更新的实体对这些实体该动作没有效果has no effect。在 Home Assistant 动作总览页 中所有动作按集成域分组展示每个动作都有独立的文档页包含 UI 分步操作、示例和完整的数据字段参考——本页即是其中一个条目见 动作文档源文件 的 front matteraction: homeassistant.update_entity、domain: homeassistant。在用户界面中使用官方文档给出的 UI 操作流程如下适用于自动化和脚本两种载体进入SettingsAutomations scenes设置 自动化与场景。打开一个已有的自动化或脚本或选择Create automationCreate new automation新建。如果是新建自动化先在When触发条件区域添加触发器脚本则不需要触发器它们由其他动作调用时执行。在Then do执行动作区域选择Add action。搜索并选择Update entity。在Entities to update要更新的实体下选择一个或多个需要刷新的实体。选择Save保存。UI 中的选项动作文档中通过options_ui代码块声明的 UI 选项只有一个选项说明Entities to updateOne or more entities to refresh right away.一个或多个需要立即刷新的实体从源码结构看该 UI 选项表并非手工排版的表格而是由文档站自定义 Liquid 标签渲染的options_ui.rb 定义了Jekyll::OptionsUiBlock它会解析标签内的 YAML 映射为每个选项强制要求description缺失时抛出ArgumentError并渲染出config-vars basic结构的 HTML同时支持显示 Required/Optional 徽标。这也意味着动作文档里的选项说明与最终页面展示是同源生成的维护文档即维护页面。在 YAML 中使用在 YAML 中该动作的调用名称为homeassistant.update_entity。官方文档给出的基础示例原文完整保留action: | action: homeassistant.update_entity data: entity_id: - sensor.outdoor_temperature - sensor.living_room_humidity这段 YAML 的语义是让sensor.outdoor_temperature室外温度与sensor.living_room_humidity客厅湿度两个实体立即刷新数据。entity_id支持列表因此可以一次指定多个实体。YAML 中的选项字段类型必填说明entity_idlist列表是required: trueOne or more entities to refresh right away.一个或多个需要立即刷新的实体渲染机制上YAML 选项区块由 options_yaml.rb 中的Jekyll::OptionsYamlBlock处理它复用 configuration.rb 中的共享ConfigurationBlock逻辑输出config-vars布局与 UI 选项区块共用同一套 CSS 样式。示例代码块的呈现则来自 example.rb 中的Jekyll::ExampleBlock该插件将action键的块解析为 Action 类型的输入示例以 YAML 语法高亮渲染并在存在output键时额外生成 Result 输出区。使用边界防抖与定向方式的限制这部分是对原文档 Good to know 小节的补充依据是仓库内引用该动作的 自定义轮询任务文档被 通用任务页 等页面复用10 秒防抖debouncehomeassistant.update_entity带有 10 秒防抖即通过该动作刷新同一实体时两次请求之间至少间隔 10 秒才有效。如果你的自动化在极短时间内重复触发该动作超出防抖窗口的请求不会每次都导致真实刷新。仅支持按实体定向该动作只支持通过entity_id指定实体。在 UI 中尝试选择区域area、设备device或标签label作为定向目标是不被支持的必须落到具体实体。结合原文档 Good to know 的两条提醒完整的语义边界为该动作请求立即更新实体的正常更新计划保持不变对本身不按计划轮询的实体该动作无效同一实体的刷新请求受 10 秒防抖限制定向只能到实体粒度。实战场景自定义轮询自动化仓库文档中将该动作用于自定义设备轮询间隔的完整步骤如下摘自 define_custom_polling.md可作为homeassistant.update_entity的标准用法模板进入SettingsDevices services设置 设备与服务选中目标集成。在集成条目上选择竖向三点菜单进入System options系统选项关闭默认轮询disable polling。创建一个自动化来定义你自己的轮询间隔进入SettingsAutomations scenes新建自动化定义任意的触发器与条件选择Add actionOther actionsPerform action然后从动作列表中选择homeassistant.update_entity在Entity字段中加入要轮询的实体。注意该动作只支持按实体定向不能选区域、设备或标签。保存自动化。此后实体的刷新节奏完全由你的触发器例如定时触发控制而不受集成默认轮询间隔约束。另一种常见组合是在自动化动作序列中先执行homeassistant.update_entity刷新目标传感器再由后续动作如notify、模板渲染读取新鲜值。此时需要留意 10 秒防抖——如果同一自动化可能在一秒内被触发两次第二次刷新会被防抖窗口吞掉。相关动作与求助渠道该文档 front matter 中声明的关联动作为 homeassistant.reload_config_entryReload config entry无需重启 Home Assistant 即可重新加载某个集成的配置条目。两者定位不同但互补homeassistant.update_entity作用于实体数据层让已有实体刷新一次数据homeassistant.reload_config_entry作用于集成配置层整体卸载并重新设置某个配置条目。若集成已经无响应刷新实体不会恢复连接此时应优先考虑 reload。文档页末尾由 related.md 模板自动根据site.actions数据把related_actions渲染成 Related actions 链接列表因此关联动作关系只维护在 front matter 中。如果配置后仍然遇到问题原文档通过 stuck.md 提供了社区求助渠道Home Assistant Discord、社区论坛与 /r/homeassistant 子版发帖时建议附上你调用的动作名与预期行为。小结homeassistant.update_entity是一个立即刷新一次的动作UI 上对应Update entityYAML 上写action: homeassistant.update_entitydata.entity_id必填列表类型。它不改变实体的正常更新计划对非轮询型实体无效受 10 秒防抖限制只能按实体定向。最典型的落地场景是禁用默认轮询 自建轮询自动化用该动作精确控制数据刷新时机当集成本身失联时应改用homeassistant.reload_config_entry。文档站中这些内容均由 actions/ui_header.md、actions/yaml_header.md 等共享包含与 options_ui.rb、options_yaml.rb、example.rb 插件统一渲染阅读源文件即可复现每个动作页面的完整结构。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考