将 Apple Health 数据同步到 REST API
将健康数据发送到 REST API 端点。
Last updated: February 6, 2026
On this page
REST API 自动化允许您自动将健康数据导出到接受 HTTP POST 请求的任何 Web 服务。这对于与自定义后端、第三方 API 或 Webhook 集成非常理想。
概述
REST API 自动化使用 HTTP POST 请求将您的健康数据发送到指定的 URL 端点。自动化可以以 JSON 或 CSV 格式发送数据，具有用于身份验证和自定义元数据的可配置标头。
使用场景:
- 与自定义后端服务集成
- 向 Webhook 发送数据
- 与第三方 API 同步
- 构建自定义仪表板或分析平台
主要功能:
- 支持 JSON 和 CSV 格式
- 用于身份验证的自定义 HTTP 标头
- 可配置的请求超时
- 手动导出历史数据
限制
健康数据访问: 当 iPhone 锁定时，应用不允许访问健康数据。自动化只会在设备解锁期间运行。这可能会影响数据的新鲜度。请参阅手动同步说明以保持数据最新。
后台处理: iOS 限制后台处理以保持电池寿命。自动化依赖于后台应用刷新，在以下情况下可能不会立即运行:
- 应用的后台应用刷新已禁用
- 设备处于低电量模式
- 设备长时间处于非活动状态
- 系统资源受限
- 多个应用竞争后台执行时间
先决条件
- 接受 HTTP POST 请求的有效 URL 端点
- 身份验证凭据（如果您的端点需要）
- 到达您的端点的网络连接
配置
从主导航导航到自动导出屏幕，然后点击"新建自动化"并选择"REST API"作为自动化类型。
自动化名称
为您的自动化输入描述性名称（例如，"我的后端 API"、"Webhook 集成"）。
通知
配置何时接收通知:
- 缓存更新时通知 - 当缓存数据更新时接收通知
- 运行时通知 - 每次自动化执行时接收通知
URL 配置
输入您要发送健康数据的完整 URL。这应该是包含协议（http:// 或 https://）的完整 URL。
URL 示例:
https://api.example.com/health-datahttps://webhook.site/your-unique-idhttp://localhost:3000/api/health
注意: URL 必须有效且可从您的设备访问。无效的 URL 将阻止自动化运行。
请求超时
选择 HTTP 请求的超时间隔。这决定了应用在认为请求失败之前等待响应的时间。
HTTP 标头
添加用于身份验证或元数据的自定义 HTTP 标头。常见用例包括:
- API 密钥:
X-API-Key: your-api-key - 授权令牌:
Authorization: Bearer your-token - 内容类型覆盖:
Content-Type: application/json
要添加标头:
- 点击"添加标头"
- 在左侧字段中输入标头键
- 在右侧字段中输入标头值
- 为其他标头重复
重要: 每个标头键必须具有相应的值。空标头将被忽略。
数据类型设置
数据类型
选择要导出的健康数据类型:
- 健康指标 - 步数、心率、睡眠和其他健康测量值
- 锻炼 - 运动和健身活动
- 症状 - 健康症状和状况
- 心电图 - 心电图读数
- 心率通知 - 高/低心率事件
- 心理状态 - 情绪和心理状态条目（iOS 18.0+）
- 周期跟踪 - 月经周期和生殖健康数据
- 药物 - 药物日志和依从性（iOS 26.0+）
健康指标配置
选择健康指标时:
选择健康指标 - 选择要包含的特定指标。您可以选择所有可用指标或选择特定指标。
提示: 仅选择您需要的指标可以改善处理时间并减少数据大小。
首选来源 - 配置当多个来源提供相同指标时哪些数据源具有优先级。
锻炼配置
选择锻炼时:
包含路线数据 - 打开以包含具有位置数据的锻炼路线。
包含锻炼指标 - 打开以包含锻炼期间收集的健康指标（心率、卡路里等）。
时间分组（锻炼指标） - 使用导出版本 2 且启用包含锻炼指标时:
- 分钟 - 按分钟分组锻炼指标
- 秒 - 按秒分组锻炼指标
导出设置
导出格式
选择导出数据的格式:
JSON 格式 - 提供具有嵌套对象的详细数据结构。最适合需要结构化数据的 API、数据库和应用程序。JSON 格式包含更复杂数据类型（如睡眠阶段和 AFib 读数）的详细信息。
CSV 格式 - 提供可轻松导入电子表格应用程序的表格数据。最适合简单数据分析或您的端点期望 CSV 数据时。
注意: Content-Type 标头对于 JSON 导出自动设置为 application/json，对于 CSV 导出设置为 multipart/form-data。
导出版本
选择导出版本。版本控制允许您以自己的节奏在导出的更新版本之间转换，并最大程度地减少破坏工作流的更改。
- 版本 1 - 旧格式，如果您有依赖此格式的现有工作流，请使用
- 版本 2 - 具有增强的锻炼数据和更详细的元数据选项的当前格式
日期范围
选择何时导出数据:
- 默认 - 同步前一天的完整数据加上到当前日期和时间的数据
- 自上次同步 - 每次同步时，导出自上次运行导出到当前日期和时间的所有数据
- 今天 - 同步当前日期到当前时间的所有数据
- 昨天 - 同步前一天的完整所有数据
- 过去 7 天 - 同步过去七天的完整数据
汇总数据
使用健康指标数据类型和 JSON 格式时，打开或关闭汇总数据。
- 开启 - 提供聚合的数据摘要
- 关闭 - 尽可能提供非聚合数据，显示单个数据点
注意: 此设置仅适用于具有健康指标的 JSON 格式。使用 CSV 格式或选择多个指标时，数据始终会被聚合。
时间分组
使用启用汇总数据的 JSON 格式时，选择应如何聚合数据。
注意: CSV 格式始终聚合数据。分钟和秒级别的聚合可能会显著增加处理时间和数据大小。
批量请求
使用 JSON 格式时，打开批量请求以通过多个请求批量发送数据，而不是单个有效负载。
- 开启 - 将数据分散到多个请求中以避免过大的有效负载
- 关闭 - 在单个请求中发送所有数据
同步频率
配置自动化应多久上传一次数据:
选择一个数字和间隔。
测试和验证
手动测试
- 在自动化配置屏幕中点击"手动导出"
- 选择日期范围
- 点击"导出"以发送测试请求
- 检查您的端点以确认数据已接收
查看活动日志
- 在自动化配置屏幕中点击"查看活动日志"
- 查看最近的自动化运行
- 检查是否有错误或警告
- 验证请求时间戳和响应状态
验证数据格式
应用会自动在每个请求中包含以下标头:
Content-Type- 根据导出格式设置automation-name- 您的自动化名称automation-id- 自动化的唯一标识符automation-aggregation- 所选的时间分组automation-period- 所选的日期范围session-id- 每个请求的唯一标识符
故障排除
常见问题
端点未收到数据
- 验证端点 URL 是否正确
- 检查您的端点是否接受 POST 请求
- 查看身份验证标头
- 检查端点的传入请求日志
- 验证网络连接
提示和最佳实践
性能:
- 使用适当的时间分组来平衡详细信息与数据大小
- 仅选择您需要的指标
可靠性:
- 根据端点的响应时间设置适当的超时值
- 定期监控活动日志
数据格式:
- 对结构化数据和 API 使用 JSON
- 对简单数据分析或电子表格集成使用 CSV
- 考虑对大型数据集或单独处理使用批量请求