REST API 自动化指南

REST API 自动化允许您自动将健康数据导出到接受 HTTP POST 请求的任何 Web 服务。这对于与自定义后端、第三方 API 或 Webhook 集成非常理想。

概述

REST API 自动化使用 HTTP POST 请求将您的健康数据发送到指定的 URL 端点。自动化可以以 JSON 或 CSV 格式发送数据，具有用于身份验证和自定义元数据的可配置标头。

使用场景:

• 与自定义后端服务集成
• 向 Webhook 发送数据
• 与第三方 API 同步
• 构建自定义仪表板或分析平台

主要功能:

• 支持 JSON 和 CSV 格式
• 用于身份验证的自定义 HTTP 标头
• 可配置的请求超时
• 手动导出历史数据

限制：

• 健康数据访问： iPhone 锁定时，App 无法访问健康数据。自动化仅在设备解锁期间运行。这是 Apple 施加的限制，无法绕过。更多信息

• 后台处理： iOS 为节省电量会限制后台处理。自动化依赖“后台 App 刷新”，在以下情况下可能不会立即运行：

  • 已为该 App 关闭“后台 App 刷新”
  • 设备处于低电量模式
  • 设备长时间未活动
  • 系统资源紧张
  • 多个 App 竞争后台执行时间

性能

请注意，iOS 针对移动设备上约束严格的短时任务进行了优化。后台任务通常须在 30 秒内完成，且可用内存有限。Health Auto Export 提供很高的灵活性和可定制性，因此了解某些配置如何影响应用性能和结果很重要。

• 配置： 产生大量数据的自动化可能导致系统终止进程，从而使自动化无法在后台运行。以下配置可能产生大量数据：
  • 配置为导出所有健康指标的自动化。
    • 建议： 仅选择 Apple 健康中已有数据的健康指标，以及您实际计划使用的数据。即使是空数据类型也会影响性能。您也可以考虑将所选健康指标拆分到多个自动化中，便于系统处理。
  • 使用秒或分钟时间分组，或关闭数据汇总的自动化。如此细粒度的查询可能耗时较长，并与系统限制冲突。
    • 建议： 尽管尽可能详细的数据看似理想，请考虑每个指标或数据类型是否真的需要该粒度。可考虑使用不同设置的多个自动化。
  • 导出户外锻炼（如骑行、跑步、徒步等）并包含路线数据时，GPS 及相关健康指标数据可能产生很大的负载。
• 负载大小： 尤其是使用 REST API 导出时，过大的负载可能导致服务器错误。请确保后端能处理可能达数百兆字节的负载。
• 同步频率： 将自动化小组件添加到主屏幕，有助于确保自动化在后台成功运行（参见设置自动化小组件）。

先决条件

• 接受 HTTP POST 请求的有效 URL 端点
• 身份验证凭据（如果您的端点需要）
• 到达您的端点的网络连接

配置

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

自动化名称

为您的自动化输入描述性名称（例如，"我的后端 API"、"Webhook 集成"）。

通知

配置何时接收通知:

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

URL 配置

输入您要发送健康数据的完整 URL。这应该是包含协议（http:// 或 https://）的完整 URL。

URL 示例:

• https://api.example.com/health-data
• https://webhook.site/your-unique-id
• http://localhost:3000/api/health

注意: URL 必须有效且可从您的设备访问。无效的 URL 将阻止自动化运行。

请求超时

选择 HTTP 请求的超时间隔。这决定了应用在认为请求失败之前等待响应的时间。

HTTP 标头

添加用于身份验证或元数据的自定义 HTTP 标头。常见用例包括:

• API 密钥: X-API-Key: your-api-key
• 授权令牌: Authorization: Bearer your-token
• 内容类型覆盖: Content-Type: application/json

要添加标头:

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

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

数据类型设置

数据类型

选择要导出的健康数据类型:

• 健康指标 - 步数、心率、睡眠和其他健康测量值
• 锻炼 - 运动和健身活动
• 症状 - 健康症状和状况
• 心电图 - 心电图读数
• 心率通知 - 高/低心率事件
• 心理状态 - 情绪和心理状态条目（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 格式时，打开 批量请求，通过多个 HTTP 请求发送数据，而不是单个大型负载。

• 开 — 将数据分散到多个请求。当端点有负载大小限制、大型正文超时或需要增量处理时使用。
• 关 — 在单个请求中发送所有数据。适用于较小的导出和简单 Webhook。

何时启用批量：

• 选择了许多健康指标、较长的日期范围或精细的时间分组（分钟/秒）
• 汇总数据已关闭且导出未聚合的健康指标
• 服务器对大型 POST 正文返回错误或超时

说明：

• 批量请求仅适用于 REST API + JSON（不适用于 CSV）。
• 批量可减小每个请求的负载，但不会消除在设备上获取数据的需要；缓慢的 HealthKit 查询仍可能作为警告出现在活动日志中。请参阅活动日志中的缓慢查询。

同步频率

配置自动化应多久上传一次数据:

选择一个数字和间隔。

测试和验证

手动测试

1. 在自动化配置屏幕中点击"手动导出"
2. 选择日期范围
3. 点击"导出"以发送测试请求
4. 检查您的端点以验证数据是否已收到

查看活动日志

1. 在自动化配置屏幕中轻点 查看活动日志。
2. 查看 运行（按时间分组，最新的在前），并展开每次运行中的事件。
3. 区分 警告（例如健康数据查询缓慢）与 错误（HTTP 失败、超时或 HealthKit 读取失败）—请参阅自动化概览 — 活动日志。
4. 成功的 REST 上传通常在运行中显示包含格式、数据类型、导出周期和日期范围的摘要。
5. 共享（工具栏）可导出完整的应用事件日志诊断 ZIP 以供支持（与设置 → 高级）。
6. 清除仅清除此自动化的活动历史。

验证数据格式

应用会自动在每个请求中包含以下标头:

• Content-Type - 根据导出格式设置
• automation-name - 您的自动化名称
• automation-id - 自动化的唯一标识符
• automation-aggregation - 所选的时间分组
• automation-period - 所选的日期范围
• session-id - 每个请求的唯一标识符

故障排除

常见问题

端点未收到数据

• 验证端点 URL 是否正确
• 检查您的端点是否接受 POST 请求
• 查看身份验证标头
• 检查端点的传入请求日志
• 验证网络连接
• 查看活动日志中的 HTTP 状态码和每日失败情况

提示和最佳实践

1. 自动同步：
   • 为设备充电并使用 iPhone 镜像
     • 充电时 iOS 对性能限制较少，数据可以更频繁地同步
     • 使用 iPhone 镜像时，设备行为如同已解锁。Health Auto Export 即可访问健康数据以运行自动化操作
2. 性能：
   • 使用适当的时间分组来平衡详细信息与数据大小
   • 仅选择您需要的指标
   • 对大型 JSON 负载启用 批量请求（参见批量请求和大型负载）
   • 关注活动日志中的慢查询警告；如果运行缓慢，减少指标或使用更粗的分组
3. 可靠性：
   • 根据端点的响应时间设置适当的超时值
   • 定期监控活动日志
4. 数据格式：
   • 对结构化数据和 API 使用 JSON
   • 对简单数据分析或电子表格集成使用 CSV
   • 考虑对大型数据集或单独处理使用批量请求