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 整合"）。

通知

設定何時接收通知:

• 快取更新時通知 - 當快取資料更新時接收通知
• 執行時通知 - 每次自動化執行時接收通知

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