Home Assistant 的 recorder.get_statistics 动作详解在自动化与脚本中检索长期统计数据【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iorecorder.get_statistics是 Home Assistant 中用于从 Recorder 数据库检索长期统计Long-term statistics的核心动作它可以把实体的历史聚合值均值、最小值、最大值、累计和等以响应变量的形式返回给后续步骤使用。本文以 recorder.get_statistics 官方动作文档 为主体结合 Recorder 集成文档完整讲解该动作的适用条件、UI 与 YAML 两种配置方式、全部参数含义、响应数据结构以及如何用它实现本周能耗对比上周这类典型自动化场景。Recorder 与长期统计数据的关系要理解recorder.get_statistics首先要了解它背后的数据来源。Recorder 集成负责把 Home Assistant 中每个实体的状态变化和系统事件写入数据库官方文档描述了这样一条数据流家中某个设备状态变化 → Home Assistant 注册为状态变化或事件 → Recorder 写入数据库 → 历史、活动、仪表盘图表和统计等功能从数据库读取数据参见 Recorder 集成文档。长期统计数据就是在这条数据流末端、由数据库按时间周期聚合出的结果。recorder.get_statistics动作直接面向这部分数据因此它有一个关键前提只有存储了长期统计数据的实体才能返回结果。如果一个实体没有存储长期统计数据它就不会出现在响应中见原文档 Good to know 部分。动作的用途与运行权限该动作的核心能力是在一个时间范围内为一个或多个实体检索长期统计值统计口径包括均值mean、最小值min、最大值max、累计和sum等。官方文档给出的典型场景是自动化或脚本需要历史数值时使用例如把本周的能源使用量与上周进行比较见 recorder.get_statistics.markdown。该动作有两个重要特性通过响应变量返回结果动作执行后数据会写入response_variable指定的变量中可以在同一自动化或脚本的后续步骤里继续引用见原文档第 15 行。仅管理员可运行只有具有管理员权限的用户才能调用该动作见原文档第 17 行。与它配合使用的关联动作包括 recorder.purge清理 Recorder 数据库、recorder.purge_entities按实体清理、recorder.enable恢复记录 和 recorder.disable暂停记录它们共同构成对 Recorder 数据生命周期的完整管理。从 UI 界面使用该动作如果你习惯使用可视化界面创建自动化官方文档给出了完整的操作路径见原文档第 25-33 行进入设置自动化与场景Automations scenes。打开一个已有的自动化或脚本如果是新建选择创建自动化创建新自动化。新建自动化时在When当部分添加一个触发器脚本则不需要触发器它们在被其他东西调用时运行。在Then do然后执行部分选择添加动作Add action。在动作列表中搜索并选择Get Recorder statistics获取 Recorder 统计。设置你想要使用的选项。点击保存。UI 模式下无需编写 YAML所有选项均由界面引导完成。UI 中的选项UI 表单中各选项的含义如下整理自原文档 Options in the UI 部分UI 选项含义是否必填Statistic IDs统计 ID要返回统计数据的实体或统计项是Start time开始时间统计时间段的起点是End time结束时间统计时间段的终点如果省略则返回从开始时间起的所有统计否Period周期统计值按什么时间粒度分组可选5minute、hour、day、week、month、year是Types类型要返回的值类型可选一个或多个change、last_reset、max、mean、min、state、sum是Units单位可选的单位换算映射按设备类别提供目标单位将统计值从数据库中存储的单位转换为目标单位否在 YAML 中使用该动作在 YAML 中该动作的引用名是recorder.get_statistics。官方文档给出的完整示例见原文档第 58-75 行如下action: recorder.get_statistics data: statistic_ids: - sensor.energy_meter - sensor.water_usage start_time: 2025-06-10 00:00:00 end_time: 2025-06-11 23:00:00 period: hour types: - sum - mean units: energy: kWh volume: L response_variable: consumption_stats这个示例同时查询了电能表sensor.energy_meter和用水量sensor.water_usage两个统计源以小时为粒度、按sum与mean两种口径聚合并把结果存入consumption_stats响应变量供后续步骤使用。YAML 参数参考各参数的字段名、类型与必填性如下整理自原文档 Options in YAML 部分参数类型必填说明statistic_idslist是要返回统计数据的实体或统计项列表start_timestring是统计时间段的起点格式如2025-06-10 00:00:00end_timestring否统计时间段的终点省略时返回从开始时间起的所有统计periodstring是分组的统计周期可选5minute、hour、day、week、month、yeartypeslist是要返回的值类型可选一个或多个change、last_reset、max、mean、min、state、sumunitsmap否可选的单位换算映射按设备类别指定目标单位如energy: kWh、volume: L用于将数据库中存储的单位转换为目标单位在 YAML 中除了通过response_variable接收结果外还可以把整个动作包装进自动化或脚本的动作列表中。例如一个每日对比上周同期用电的自动化骨架alias: 对比本周与上周用电 triggers: - trigger: time at: 06:00:00 actions: - action: recorder.get_statistics data: statistic_ids: - sensor.energy_meter start_time: {{ today_at() - timedelta(days7) }} end_time: {{ now() }} period: day types: - sum response_variable: last_week_stats其中开始与结束时间可以使用模板动态生成这正是该动作与自动化组合时的常见做法——start_time、end_time均接受日期时间字符串配合模板即可实现滚动时间窗口的对比分析。响应数据结构动作执行后响应以statistics为键按你请求的每个统计 ID 分组每个统计 ID 下是一个周期列表每个周期始终包含start和end再加上你在types中指定的值类型字段见原文档 Response data 部分start周期的开始时间。end周期的结束时间。change周期内的数值变化量。last_reset计量型数值最后一次重置的时间。max周期内的最高值。mean周期内的平均值。min周期内的最低值。state周期内记录的状态。sum周期结束时的累计总数。官方文档给出的缩短版响应示例见原文档第 122-133 行statistics: sensor.energy_meter: - start: 2025-06-10T00:00:0000:00 end: 2025-06-10T01:00:0000:00 sum: 1234.5 mean: 0.42 - start: 2025-06-10T01:00:0000:00 end: 2025-06-10T02:00:0000:00 sum: 1236.1 mean: 0.39上例中因为types指定了sum和mean所以每个周期除start/end外只包含sum与mean两个字段。在自动化后续步骤中可以通过consumption_stats.statistics[sensor.energy_meter]结合模板语法访问这些数据例如取出最后一周期的sum值参与计算或展示。注意事项与最佳实践结合原文档 Good to know 部分与 Recorder 集成的行为使用该动作时有几点值得注意只有存储长期统计的实体才返回数据。如果一个实体没有统计数据它不会出现在响应中因此对空结果要做兼容处理例如判断变量是否存在。types决定每个周期的字段构成无论选择哪些类型start和end始终存在其余字段由types决定见原文档第 138 行。长期统计与 Recorder 配置相关Recorder 的include/exclude过滤配置会决定哪些实体被记录见 Recorder 集成文档被过滤掉的实体自然也无法通过本动作查询到统计如需长期保存聚合数据可配合recorder.purge设置合适的purge_keep_days与auto_purge策略控制数据库增长见 recorder.purge 动作文档。管理员权限该动作仅限管理员用户运行普通用户调用会失败。小结recorder.get_statistics是连接历史数据与自动化决策的关键桥梁通过statistic_ids、start_time/end_time、period、types与可选的units五个维度它能把数据库中长期统计的聚合结果以结构化响应变量的形式交给自动化或脚本使用。无论你是通过可视化界面逐步配置还是在 YAML 中直接编写掌握其参数语义与响应结构就能实现能耗对比、趋势分析、周期性汇总等实用的自动化逻辑。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考