将 Apple 健康数据同步到 REST API
将健康数据发送到 REST API 端点。
最后更新: 2026年10月31日
本页目录
将健康导出发送到接受 HTTP POST 请求的端点。
重要 — 自动化限制: 读取健康数据时设备必须解锁,且 iOS 不保证按您选择的频率执行后台运行。依赖自动导出前,请先查看自动化限制。
打开自动化
在 iPhone 上打开 导出 → 自动化,或在 iPad 边栏打开 自动化。选择 新建自动化,或打开现有自动化进行编辑。
名称、状态和通知
输入用于识别此自动化的名称。启用 允许自动运行;准备好之前请保持关闭。
选择所需的运行通知:
- 缓存更新时通知 报告导出数据已准备好。
- 运行时通知 报告已成功上传到端点。
出现提示时请允许通知。这些通知报告活动,不会安排运行。
设置端点
- 将 自动化类型 选为 REST API。
- 输入 iPhone 或 iPad 可到达的 URL,例如
https://api.example.com/health-data。 - 在 HTTP 标头 下添加所需身份验证。例如,键为
Authorization,值为Bearer YOUR_TOKEN。 - 选择适合端点的 请求超时。
每个标头都需要键和值。对于另一台设备上的服务器,请使用可到达的网络地址,而不是 localhost。
数据类型设置
为此自动化选择一种 数据类型:健康指标、锻炼、症状、ECG、心率通知、心理状态、周期跟踪或药物。心理状态需要 iOS 18 或更高版本;药物需要 iOS 26 或更高版本以及单独的药物访问权限。
健康指标
选择 健康指标,然后打开 选择健康指标 并选择所需测量值。
若要将读数限制为特定 App 或设备,打开 首选来源,选择指标并选择其来源。全部 允许所有未排除的来源。使用 排除的来源 可在此自动化的健康指标中忽略某个来源。排除优先;首选来源没有数据时,不会用未选来源替代。选择 保存 应用来源选择,或 取消 丢弃。
锻炼
选择 锻炼 以导出锻炼记录。包含路线数据 会将可用路线点添加到 JSON 锻炼数据。它不会创建单独的 GPX 上传。
对于 版本 2,打开 包含锻炼指标 以添加心率、活动能量和步数等读数。为锻炼指标 时间分组 选择 分钟 或 秒;秒更详细,导出也更大。版本 1 始终包含锻炼指标。
导出设置
导出格式
- JSON 为集成和分析保留结构化数据。
- CSV 创建适合电子表格的表格文件。
- Markdown 创建可读的标题和表格,适合笔记与归档。
导出版本
选择 版本 2 以使用当前数据结构。现有工作流依赖旧格式时使用 版本 1。
日期范围
| 选择 | 包含的数据 |
|---|---|
| 默认 | 前一天以及运行时刻之前的今天 |
| 自上次同步以来 | 自上次同步至运行时刻 |
| 今天 | 运行时刻之前的今天 |
| 昨天 | 前一个完整日 |
| 过去 7 天 | 过去完整的七天 |
汇总数据与时间分组
对于 JSON + 健康指标,打开 汇总数据 可将读数合并到时间分组,或在支持时关闭以保留单独读数。汇总取决于指标——例如步数合计、体重读数取平均。CSV 健康指标导出使用汇总数据。
当 时间分组 可用时,选择要保留的详细程度。按小时或按日的分组比按分钟或秒产生更少的行。可用选项取决于日期范围和格式。锻炼时间分组在锻炼设置中单独配置。
批量请求与大型负载
对于 REST API + JSON,打开 批量请求 可跨多个请求发送数据。在端点拒绝大型正文或大型请求超时时使用。接收服务必须分别处理每个请求。
CSV 和 Markdown 不支持批处理。它会减小单个请求的大小,但不会减少设备需要读取的健康数据量。若准备缓慢,请参阅性能。
排程提醒
若希望收到解锁并打开 App 的提示,请打开 启用提醒。选择 每小时、每天 或 选定日期,然后按需设置分钟、时间和日期。出现提示时允许通知访问;若被拒绝,请使用 打开通知设置。
提醒不会运行自动化,也不确认同步成功。点按可打开自动化,或使用通知上的 打开并同步 请求运行。自动化必须已启用;后台运行成功后仍可能出现提醒。提醒更改在保存时应用。
同步频率并保存
在 同步频率 下选择数字以及 分钟、小时、天 或 周——例如每 15 分钟。这是期望的后台节奏,不是保证的排程。
读取健康数据时设备必须解锁。为 Health Auto Export 启用后台 App 刷新,并为自动运行关闭低电量模式。设备长时间未使用或系统资源有限时,iOS 仍可能延迟运行。
准备好自动运行时打开 启用,然后选择 更新 保存自动化。可按下列步骤立即上传选定日期范围。
请求标头
App 会为所选格式设置 Content-Type,并包含:
| 标头 | 含义 |
|---|---|
automation-name |
自动化名称 |
automation-id |
自动化标识符 |
automation-aggregation |
所选时间分组 |
automation-period |
所选日期范围 |
session-id |
请求标识符 |
导出历史或遗漏的数据
首次设置自动化时使用 手动上传 导出历史数据,或之后补齐自动同步遗漏的日期。也可用于检查设置。
- 打开自动化,在 导出现有数据 下选择 手动上传。
- 设置 开始 和 结束 日期,然后选择 开始导出。
- 检查端点收到的请求、标头和正文。
故障排除
- 未收到请求: 检查 URL、网络可达性和服务器日志。
- 身份验证错误: 检查标头键、令牌和端点权限。
- 负载被拒绝或超时: 检查服务器大小限制,对 JSON 使用批处理,或减小导出大小。
打开自动化并选择 查看活动日志 以查看运行。警告 标记潜在问题(例如数据检索缓慢);错误 标识失败步骤。报告问题的帮助请参阅获取帮助。