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 集成"）。

通知

配置何时接收通知:

• 缓存更新时通知 - 当缓存数据更新时接收通知
• 运行时通知 - 每次自动化执行时接收通知
• 计划提醒 — 可选提示，提醒您解锁并打开 App。参见自动化概览。与运行时通知分开。

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）。
• 批量可减小每个请求的负载，但不会消除在设备上获取数据的需要；缓慢的 Apple Health 查询仍可能作为警告出现在活动日志中。请参阅活动日志中的缓慢查询。

同步频率

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

选择一个数字和间隔。

测试和验证

手动测试

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

查看活动日志

1. 在自动化配置屏幕中轻点 查看活动日志。
2. 查看 运行（按时间分组，最新的在前），并展开每次运行中的事件。
3. 警告（例如健康数据查询缓慢）与 错误（HTTP 失败、超时，或 “No health data was found in this date range, so nothing was uploaded.” 和 “Health data could not be fully read. The device may have locked during the export. Nothing was uploaded.” 等编码信息）—请参阅自动化概览 — 活动日志。
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
   • 考虑对大型数据集或单独处理使用批量请求