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 提供很高的彈性與自訂能力，因此了解某些設定如何影響 App 效能與結果很重要。

• 設定： 產生大量資料的自動化可能導致系統終止程序，使自動化無法在背景執行。以下設定可能產生大量資料：
  • 設定為匯出所有健康指標的自動化。
    • 建議： 僅選擇 Apple 健康中已有資料的健康指標，以及您實際計畫使用的資料。即使是空的資料類型也會影響效能。您也可以考慮將所選健康指標拆分到多個自動化中，便於系統處理。
  • 使用秒或分鐘時間分組，或關閉資料摘要的自動化。如此細緻的查詢可能耗時較長，並與系統限制衝突。
    • 建議： 儘管盡可能詳細的資料看似理想，請考慮每個指標或資料類型是否真的需要該粒度。可考慮使用不同設定的多個自動化。
  • 匯出戶外運動（如騎車、跑步、健行等）並包含路線資料時，GPS 及相關健康指標資料可能產生很大的承載量。
• 承載大小： 尤其是使用 REST API 匯出時，過大的承載可能導致伺服器錯誤。請確保後端能處理可能達數百 MB 的承載。
• 同步頻率： 將自動化小工具加入主畫面，有助於確保自動化在背景成功執行（參閱設定自動化小工具）。

先決條件

• 接受 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. 分享（工具列）可匯出完整的App 事件記錄診斷 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
   • 考慮對大型資料集或單獨處理使用批次要求