irvinlim/apple-health-ingester

Apple Health Ingester

用Go编写的简单HTTP服务器，用于从Health Auto Export接收数据并导入到多个可配置的存储后端。

工具背景

Health Auto Export iOS应用允许您轻松地将Apple Health数据从iOS设备导出为便携格式。然而，它目前仅支持以下导出方式：

• iCloud Drive
• REST API
• Home Assistant
• MQTT

因此，这个简单的HTTP服务器通过REST API导出方式接收来自Health Auto Export应用的请求，从而能够灵活地将数据导出到一个或多个配置的后端。

setup 说明

您需要先在iOS设备上下载Health Auto Export应用。注意：您需要购买Premium版或使用免费试用版才能启用自动化功能。

在应用中，创建新的自动化（详细说明见此处）：

1. 在“自动化类型”下，选择REST API。
2. 输入服务器URL（有关运行服务器的说明见下文）。
   • URL格式应为http://your.domain/api/healthautoexport/v1/influxdb/ingest
   • 可选：为标识数据来源（即被跟踪健康数据的用户），在URL末尾添加?target=NAME，其中NAME是友好名称（如John）。这将启用目标名称跟踪。

运行服务器

本地运行

您需要go来构建服务器。

sh
$ go build -o build/ingester ./cmd/ingester/....
$ ./build/ingester --help
Usage of ./build/ingester:
      --backend.influxdb                     启用InfluxDB存储后端。
      --backend.localfile                    启用LocalFile存储后端。
      --http.authToken string                用于验证传入请求的可选授权令牌。
      --http.listenAddr string               监听地址。(默认 ":8080")
      --influxdb.authToken string            连接InfluxDB的认证令牌。
      --influxdb.metricsBucketName string    用于指标的InfluxDB桶名称。
      --influxdb.orgName string              InfluxDB组织名称。
      --influxdb.serverURL string            InfluxDB服务器URL。
      --influxdb.staticTags strings          为每个请求添加到InfluxDB的额外标签，格式为key=value。
      --influxdb.workoutsBucketName string   用于锻炼数据的InfluxDB桶名称。
      --localfile.metricsPath string         写入指标的输出路径，每个指标一个文件。所有数据按时间戳聚合，现有数据将被合并。

Docker

Docker Hub镜像即将推出！

全局配置

• http.listenAddr：监听地址。(默认 ":8080")
• http.authToken：用于验证传入请求的可选授权令牌。

支持的存储后端

LocalFile

• URL：/api/healthautoexport/v1/localfile/ingest

将接收的 payload 写入本地文件系统（JSON格式）。主要用于调试，但可轻松扩展以支持远程文件存储（如S3、Dropbox等）的文件备份。

配置

此后端默认禁用。可通过指定--backend.localfile启用。

还必须配置后端工作所需的其他字段。示例配置：

sh
$ ingester \
  --backend.localfile \
  --localfile.metricsPath=/data/health-export-metrics

注意：此存储后端目前尚不支持锻炼数据。

示例输出

将生成一个目录，其中每个指标作为单独文件存储，如下所示：

sh
$ ls -la /data/health-export-metrics
total 2604
drwxr-xr-x 96 irvin   3072 Dec 25 00:15  .
drwxr-xr-x  3 irvin     96 Dec 25 00:11  ..
-rw-r--r--  1 irvin 418389 Dec 25 00:19  active_energy_kJ.json
-rw-r--r--  1 irvin  30279 Dec 25 00:19  apple_exercise_time_min.json
-rw-r--r--  1 irvin   4755 Dec 25 00:19  apple_stand_hour_count.json
-rw-r--r--  1 irvin 124346 Dec 25 00:19  apple_stand_time_min.json
-rw-r--r--  1 irvin     72 Dec 25 00:19  basal_body_temperature_degC.json
-rw-r--r--  1 irvin 851170 Dec 25 00:19  basal_energy_burned_kJ.json
...

如果导出时指定了目标名称，则文件名会以目标名称为前缀。

InfluxDB

• URL：/api/healthautoexport/v1/influxdb/ingest

将接收的指标和锻炼数据写入配置的InfluxDB后端。

配置

此后端默认禁用。可通过指定--backend.influxdb启用。

还必须配置后端工作所需的其他字段。示例配置：

sh
$ ingester \
  --backend.influxdb \
  --influxdb.serverURL=http://localhost:8086 \
  --influxdb.authToken=INFLUX_API_TOKEN \
  --influxdb.orgName=my-org \
  --influxdb.metricsBucketName=apple_health_metrics \
  --influxdb.workoutsBucketName=apple_health_workouts

指标数据格式

所有指标存储在--influxdb.metricsBucketName指定的桶中，格式如下：

• 测量值（Measurement）：
  • 指标名称（如active_energy）+ 单位（如kJ）
  • 示例：active_energy_kJ
• 字段（Fields）：
  • 大多数指标使用qty作为字段名。
  • 部分具有多个字段的指标使用相应的字段名。例如，sleep_analysis_hr使用以下字段名：
    • inBed
    • inBedStart
    • inBedEnd
    • inBedSource
    • 其他字段可在此处查看：https://github.com/Lybron/health-auto-export/wiki/API-Export---JSON-Format
• 标签（Tags）：
  • target_name：可选，由HTTP请求中的?target=TARGET_NAME查询参数设置。
  • 可通过--influxdb.staticTags设置额外标签。

锻炼数据格式

锻炼数据存储在--influxdb.workoutsBucketName指定的桶中。锻炼数据格式较指标复杂，更多信息见：https://github.com/Lybron/health-auto-export/wiki/API-Export---JSON-Format#workouts

包含两种数据：

1. 锻炼摘要数据：包含每次锻炼的聚合统计信息（即每次锻炼一个数据点）
   • 测量值：workout
   • 字段：
     • 示例：activeEnergy_kJ
   • 时间戳：使用锻炼开始时间
2. 锻炼期间的时间序列数据：包含每分钟粒度的时间序列数据
   • 测量值：目前仅支持以下测量值：
     • heart_rate_data_bpm
     • heart_rate_recovery_bpm
   • 字段：qty
   • 时间戳：对应date字段

所有锻炼数据包含以下标签：

• 标签：
  • target_name：可选，由HTTP请求中的?target=TARGET_NAME查询参数设置。
  • workout_name：锻炼名称。
    • 示例：Walking（步行）
  • 可通过--influxdb.staticTags设置额外标签。

示例输出

!https://github.com/irvinlim/apple-health-ingester/raw/main/assets/influxdb_screenshot.png

许可证

MIT