将 Apple 健康数据同步到 MQTT
将健康数据发布到 MQTT 代理。
最后更新: 2026年10月31日
将健康导出以 JSON 形式发布到 MQTT 代理上的主题。
重要 — 自动化限制: 读取健康数据时设备必须解锁,且 iOS 不保证按您选择的频率执行后台运行。依赖自动导出前,请先查看自动化限制。
打开自动化
在 iPhone 上打开 导出 → 自动化,或在 iPad 边栏打开 自动化。选择 新建自动化,或打开现有自动化进行编辑。
名称、状态和通知
输入用于识别此自动化的名称。启用 允许自动运行;准备好之前请保持关闭。
选择所需的运行通知:
- 缓存更新时通知 报告导出数据已准备好。
- 运行时通知 报告已成功发布到代理。
出现提示时请允许通知。这些通知报告活动,不会安排运行。
设置连接
- 将 自动化类型 选为 MQTT。
- 输入代理的主机名或 IP 地址以及端口。默认端口为 1883。
- 输入 主题,例如
health/metrics。 - 为每项自动化设置唯一的 客户端 ID,若代理要求则输入用户名和密码。
代理必须可从设备到达。订阅者必须使用确切主题(含大小写)。重复使用客户端 ID 可能导致代理连接相互替换。
数据类型设置
为此自动化选择一种 数据类型:健康指标、锻炼、症状、ECG、心率通知、心理状态、周期跟踪或药物。心理状态需要 iOS 18 或更高版本;药物需要 iOS 26 或更高版本以及单独的药物访问权限。
健康指标
选择 健康指标,然后打开 选择健康指标 并选择所需测量值。
若要将读数限制为特定 App 或设备,打开 首选来源,选择指标并选择其来源。全部 允许所有未排除的来源。使用 排除的来源 可在此自动化的健康指标中忽略某个来源。排除优先;首选来源没有数据时,不会用未选来源替代。选择 保存 应用来源选择,或 取消 丢弃。
锻炼
选择 锻炼 以导出锻炼记录。包含路线数据 会将可用路线点添加到 JSON 锻炼数据。它不会创建单独的 GPX 上传。
对于 版本 2,打开 包含锻炼指标 以添加心率、活动能量和步数等读数。为锻炼指标 时间分组 选择 分钟 或 秒;秒更详细,导出也更大。版本 1 始终包含锻炼指标。
导出设置
MQTT 仅发布 JSON。前台发布使用 QoS 0,后台发布使用 QoS 1。消息不会保留。
导出版本
选择 版本 2 以使用当前数据结构。现有工作流依赖旧格式时使用 版本 1。
日期范围
| 选择 | 包含的数据 |
|---|---|
| 默认 | 前一天以及运行时刻之前的今天 |
| 自上次同步以来 | 自上次同步至运行时刻 |
| 今天 | 运行时刻之前的今天 |
| 昨天 | 前一个完整日 |
| 过去 7 天 | 过去完整的七天 |
汇总数据与时间分组
对于 JSON + 健康指标,打开 汇总数据 可将读数合并到时间分组,或在支持时关闭以保留单独读数。汇总取决于指标——例如步数合计、体重读数取平均。CSV 健康指标导出使用汇总数据。
当 时间分组 可用时,选择要保留的详细程度。按小时或按日的分组比按分钟或秒产生更少的行。可用选项取决于日期范围和格式。锻炼时间分组在锻炼设置中单独配置。
排程提醒
若希望收到解锁并打开 App 的提示,请打开 启用提醒。选择 每小时、每天 或 选定日期,然后按需设置分钟、时间和日期。出现提示时允许通知访问;若被拒绝,请使用 打开通知设置。
提醒不会运行自动化,也不确认同步成功。点按可打开自动化,或使用通知上的 打开并同步 请求运行。自动化必须已启用;后台运行成功后仍可能出现提醒。提醒更改在保存时应用。
同步频率并保存
在 同步频率 下选择数字以及 分钟、小时、天 或 周——例如每 15 分钟。这是期望的后台节奏,不是保证的排程。
读取健康数据时设备必须解锁。为 Health Auto Export 启用后台 App 刷新,并为自动运行关闭低电量模式。设备长时间未使用或系统资源有限时,iOS 仍可能延迟运行。
准备好自动运行时打开 启用,然后选择 更新 保存自动化。可按下列步骤立即上传选定日期范围。
导出历史或遗漏的数据
首次设置自动化时使用 手动上传 导出历史数据,或之后补齐自动同步遗漏的日期。也可用于检查设置。
- 将 MQTT 订阅者连接到代理并订阅配置的主题。
- 在 Health Auto Export 中打开自动化,在 导出现有数据 下选择 手动上传。
- 设置 开始 和 结束 日期,然后选择 开始导出。
- 检查收到的 JSON 及其日期。
负载遵循 JSON 导出格式。例如:
{
"data": {
"metrics": [
{
"name": "step_count",
"units": "count",
"data": [{"date": "2024-02-06 00:00:00 -0800", "qty": 8500}]
}
]
}
}
故障排除
- 连接失败: 检查主机、端口、网络访问和代理连接要求。
- 身份验证失败: 检查凭据以及对主题的发布权限。
- 无消息: 确认订阅者使用同一代理和确切主题,然后查看活动日志。
- 消息过大: 选择更少指标、更短范围或更粗的时间分组。
打开自动化并选择 查看活动日志 以查看运行。警告 标记潜在问题(例如数据检索缓慢);错误 标识失败步骤。报告问题的帮助请参阅获取帮助。