企业官网建设流程全解析

Home Assistant 的 recorder.get_statistics 动作详解：在自动化与脚本中检索长期统计数据

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

recorder.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 行）：

1. 进入设置>自动化与场景（Automations & scenes）。
2. 打开一个已有的自动化或脚本；如果是新建，选择创建自动化>创建新自动化。
3. 新建自动化时，在When（当）部分添加一个触发器；脚本则不需要触发器，它们在被其他东西调用时运行。
4. 在Then do（然后执行）部分，选择添加动作（Add action）。
5. 在动作列表中搜索并选择Get Recorder statistics（获取 Recorder 统计）。
6. 设置你想要使用的选项。
7. 点击保存。

UI 模式下无需编写 YAML，所有选项均由界面引导完成。

UI 中的选项

UI 表单中各选项的含义如下（整理自原文档 Options in the UI 部分）：

在 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 部分）：

在 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(days=7) }}" 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:00+00:00" end: "2025-06-10T01:00:00+00:00" sum: 1234.5 mean: 0.42 - start: "2025-06-10T01:00:00+00:00" end: "2025-06-10T02:00:00+00: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