HealthyApps Help Center

将 Apple Health 数据同步到 Home Assistant

将您的健康数据与 Home Assistant 集成。

Last updated: February 5, 2026

On this page

Home Assistant 自动化允许您将健康数据自动同步到 Home Assistant 作为传感器状态。此集成使您能够在 Home Assistant 自动化、仪表板和其他集成中使用您的健康数据。

概述

Home Assistant 自动化将您的健康指标发送到 Home Assistant 的 REST API，创建或更新可在整个 Home Assistant 实例中使用的传感器状态。数据专门为 Home Assistant 的 /states/ API 格式化。

使用场景:

  • 在 Home Assistant 仪表板上显示健康指标
  • 基于健康数据创建自动化
  • 将健康数据与其他智能家居设备集成
  • 在 Home Assistant 中跟踪健康趋势

主要功能:

  • 自动传感器状态创建
  • 仅 JSON 格式（针对 Home Assistant 优化）
  • 仅支持 Health Metrics 数据类型
  • 简单的 URL 配置

限制

  • 健康数据访问: 当 iPhone 锁定时，应用无法访问健康数据。自动化只会在设备解锁期间运行。这可能会影响数据的新鲜度。请参阅手动同步说明以保持数据最新。

  • 后台处理: iOS 限制后台处理以保持电池寿命。自动化依赖于应用后台刷新，在以下情况下可能不会立即运行:

    • 应用的后台刷新已禁用
    • 设备处于低电量模式
    • 设备长时间处于非活动状态
    • 系统资源受限
    • 多个应用竞争后台执行时间

  • 仅支持 Health Metrics 数据类型

  • 仅 JSON 格式（无法更改）

先决条件

  • 在您的网络上运行且可访问的 Home Assistant 实例
  • Home Assistant API 访问令牌（长期访问令牌）
  • 到您的 Home Assistant 实例的网络连接
  • 支持 REST API 的 Home Assistant 版本

配置

从主导航导航到自动化导出屏幕，然后点击"新建自动化"并选择"Home Assistant"作为自动化类型。

自动化名称

为您的自动化输入一个描述性名称。此名称将用于在 Home Assistant 中生成传感器实体 ID。

注意: 自动化名称将转换为小写并删除空格以创建实体 ID。例如，"我的健康数据"变为 hae.wodejiankangshuju。

通知

配置何时接收通知:

  • 缓存更新时通知 - 缓存数据更新时接收通知
  • 运行时通知 - 每次自动化执行时接收通知

Home Assistant URL

输入您的 Home Assistant 实例的基本 URL。如果不使用默认值，则应包括协议和端口。

URL 示例:

  • http://homeassistant.local:8123
  • http://192.168.1.100:8123

注意: URL 必须可从您的设备访问。如果使用 HTTPS，请确保您的证书有效或添加例外。

自动生成的端点

应用会根据您的自动化名称自动生成完整的 API 端点:

{your_url}/api/states/hae.{automation_name}

例如，如果您的 URL 是 http://homeassistant.local:8123 且您的自动化名称是"健康指标"，则端点将是:

http://homeassistant.local:8123/api/states/hae.jiankangzhibiao

此端点显示在 URL 字段下方作为参考。

请求超时

选择对 Home Assistant 的 HTTP 请求的超时间隔。

可用的超时选项:

  • 60 秒 - 默认值，适用于大多数 Home Assistant 实例
  • 300 秒（5 分钟） - 适用于较慢的 Home Assistant 实例
  • 1800 秒（30 分钟） - 适用于非常慢的处理
  • 3600 秒（1 小时） - 最大推荐超时

HTTP 标头

添加用于访问 Home Assistant API 的身份验证标头。您需要使用长期访问令牌添加 Authorization 标头。

必需标头:

  • Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN

要获取长期访问令牌:

  1. 打开 Home Assistant
  2. 转到您的个人资料（点击左下角的您的姓名）
  3. 向下滚动到"长期访问令牌"
  4. 点击"创建令牌"
  5. 给它一个名称（例如，"Health Auto Export"）
  6. 复制令牌并将其粘贴到标头值字段中

可选标头:
如果需要，您可以为 Home Assistant 设置添加其他标头。

要添加标头:

  1. 点击"添加标头"
  2. 在左侧字段中输入标头键
  3. 在右侧字段中输入标头值
  4. 对其他标头重复

重要: 每个标头键必须具有相应的值。空标头将被忽略。

数据类型设置

数据类型

注意: Home Assistant 自动化仅支持 Health Metrics 数据类型。此设置无法更改，并自动设置为 Health Metrics。

Health Metrics 配置

选择 Health Metrics - 选择要包含的特定指标。您可以选择所有可用指标或选择特定指标。

提示: 仅选择您需要的指标可以改善处理时间并减少发送到 Home Assistant 的数据大小。

首选来源 - 配置当多个来源提供相同指标时哪些数据源具有优先级。

导出设置

导出格式

注意: Home Assistant 自动化仅支持 JSON 格式。此设置无法更改，并自动设置为 JSON。

导出版本

注意: 导出版本不适用于 Home Assistant 自动化，因为格式专门针对 Home Assistant 的状态 API 进行了优化。

日期范围

选择何时应导出数据:

  • 默认 - 同步前一天的全部数据加上到当前日期和时间的数据
  • 今天 - 同步当前日期到当前时间的所有数据
  • 昨天 - 同步前一天的全部所有数据

注意: Home Assistant 自动化不支持"实时"、"自上次同步"或"过去 7 天"选项。

汇总数据

为 Health Metrics 打开或关闭汇总数据。

  • 开启 - 提供聚合数据摘要（默认）
  • 关闭 - 在可能的情况下提供非聚合数据

注意: 此设置仅适用于 Health Metrics 数据类型。

时间分组

启用汇总数据时，选择应如何聚合数据:

  • 默认 - 无聚合，原始数据点
  • 天 - 按天分组数据（推荐）

同步频率

配置自动化应多久与 Home Assistant 同步数据:

选择一个数字和间隔。

测试和验证

手动测试

  1. 在自动化配置屏幕上点击"手动导出"
  2. 选择日期范围
  3. 点击"导出"以发送测试请求
  4. 在 Home Assistant 中检查传感器状态是否已创建/更新

在 Home Assistant 中验证

  1. 打开 Home Assistant
  2. 转到开发者工具 > 状态
  3. 搜索 hae.{your_automation_name}（小写，无空格）
  4. 验证传感器状态显示您的健康数据
  5. 检查"最后更新"时间戳以确认最近的同步

查看活动日志

  1. 在自动化配置屏幕上点击"查看活动日志"
  2. 查看最近的自动化运行
  3. 检查是否有错误或警告
  4. 验证请求时间戳和响应状态

检查 Home Assistant 日志

如果数据未出现在 Home Assistant 中:

  1. 打开 Home Assistant
  2. 转到设置 > 系统 > 日志
  3. 查找与 REST API 或传感器状态相关的错误
  4. 检查身份验证错误或无效数据格式

故障排除

常见问题

身份验证错误

  • 验证您的长期访问令牌是否正确
  • 确保 Authorization 标头格式为: Bearer YOUR_TOKEN
  • 检查令牌是否已过期或已被撤销
  • 验证令牌在 Home Assistant 中具有适当的权限

传感器未出现在 Home Assistant 中

  • 检查自动化名称是否包含特殊字符
  • 验证实体 ID 格式: hae.{automation_name}（小写，无空格）
  • 检查 Home Assistant 日志中的错误
  • 确保 API 请求成功（检查活动日志）

数据未更新

  • 检查自动化是否已启用
  • 查看活动日志中的错误
  • 确保与 Home Assistant 的网络连接

连接超时

  • 验证 Home Assistant 是否正在运行且可访问
  • 检查网络连接
  • 如果 Home Assistant 响应缓慢，请增加请求超时设置
  • 验证 URL 和端口是否正确

错误消息

如果出现以下情况，应用将显示错误消息:

  • URL 无效或无法访问
  • 身份验证失败（检查 Authorization 标头）
  • Home Assistant 返回错误状态代码
  • 网络连接不可用

检查活动日志以获取详细的错误信息，包括 HTTP 状态代码和来自 Home Assistant 的错误消息。

Home Assistant 集成提示

在自动化中使用健康数据

健康数据与 Home Assistant 同步后，您可以在自动化中使用它们:

automation:
  - alias: "良好睡眠质量"
    trigger:
      - platform: numeric_state
        entity_id: sensor.hae_myhealthdata_sleep_total
        above: 7
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "昨晚睡眠很棒！"

创建仪表板

将健康指标添加到您的 Home Assistant 仪表板:

  1. 转到您的仪表板
  2. 添加新卡片
  3. 选择"实体"或"仪表"卡片类型
  4. 添加 hae.{your_automation_name} 传感器实体

传感器状态结构

Home Assistant 中的传感器状态包含:

  • state: 当前值或状态
  • attributes: 其他数据包括:
    • 时间戳信息
    • 与导出的 JSON 格式匹配的数据结构
    • 适用时的单位信息

提示和最佳实践

  1. 命名:

    • 避免可能导致问题的特殊字符

  2. 数据选择:

    • 仅选择您需要的指标