將 Apple Health 資料同步到 REST API
將健康資料傳送到 REST API 端點。
Last updated: February 6, 2026
On this page
REST API 自動化允許您自動將健康資料匯出到接受 HTTP POST 請求的任何 Web 服務。這對於與自訂後端、第三方 API 或 Webhook 整合非常理想。
概述
REST API 自動化使用 HTTP POST 請求將您的健康資料傳送到指定的 URL 端點。自動化可以以 JSON 或 CSV 格式傳送資料，具有用於身份驗證和自訂元資料的可設定標頭。
使用場景:
- 與自訂後端服務整合
- 向 Webhook 傳送資料
- 與第三方 API 同步
- 建構自訂儀表板或分析平台
主要功能:
- 支援 JSON 和 CSV 格式
- 用於身份驗證的自訂 HTTP 標頭
- 可設定的請求逾時
- 手動匯出歷史資料
限制
健康資料存取: 當 iPhone 鎖定時，應用程式不允許存取健康資料。自動化只會在裝置解鎖期間執行。這可能會影響資料的新鮮度。請參閱手動同步說明以保持資料最新。
背景處理: iOS 限制背景處理以保持電池壽命。自動化依賴於背景應用程式重新整理，在以下情況下可能不會立即執行:
- 應用程式的背景應用程式重新整理已停用
- 裝置處於低電量模式
- 裝置長時間處於非活動狀態
- 系統資源受限
- 多個應用程式競爭背景執行時間
先決條件
- 接受 HTTP POST 請求的有效 URL 端點
- 身份驗證憑證（如果您的端點需要）
- 到達您的端點的網路連線
設定
從主導覽導航到自動匯出畫面，然後點擊"新增自動化"並選擇"REST API"作為自動化類型。
自動化名稱
為您的自動化輸入描述性名稱（例如，"我的後端 API"、"Webhook 整合"）。
通知
設定何時接收通知:
- 快取更新時通知 - 當快取資料更新時接收通知
- 執行時通知 - 每次自動化執行時接收通知
URL 設定
輸入您要傳送健康資料的完整 URL。這應該是包含協定（http:// 或 https://）的完整 URL。
URL 範例:
https://api.example.com/health-datahttps://webhook.site/your-unique-idhttp://localhost:3000/api/health
注意: URL 必須有效且可從您的裝置存取。無效的 URL 將阻止自動化執行。
請求逾時
選擇 HTTP 請求的逾時間隔。這決定了應用程式在認為請求失敗之前等待回應的時間。
HTTP 標頭
新增用於身份驗證或元資料的自訂 HTTP 標頭。常見用例包括:
- API 金鑰:
X-API-Key: your-api-key - 授權令牌:
Authorization: Bearer your-token - 內容類型覆寫:
Content-Type: application/json
要新增標頭:
- 點擊"新增標頭"
- 在左側欄位中輸入標頭鍵
- 在右側欄位中輸入標頭值
- 為其他標頭重複
重要: 每個標頭鍵必須具有相應的值。空標頭將被忽略。
資料類型設定
資料類型
選擇要匯出的健康資料類型:
- 健康指標 - 步數、心率、睡眠和其他健康測量值
- 鍛鍊 - 運動和健身活動
- 症狀 - 健康症狀和狀況
- 心電圖 - 心電圖讀數
- 心率通知 - 高/低心率事件
- 心理狀態 - 情緒和心理狀態項目（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 格式時，開啟批次請求以通過多個請求批次傳送資料，而不是單個有效負載。
- 開啟 - 將資料分散到多個請求中以避免過大的有效負載
- 關閉 - 在單個請求中傳送所有資料
同步頻率
設定自動化應多久上傳一次資料:
選擇一個數字和間隔。
測試和驗證
手動測試
- 在自動化設定畫面中點擊"手動匯出"
- 選擇日期範圍
- 點擊"匯出"以傳送測試請求
- 檢查您的端點以確認資料已接收
檢視活動日誌
- 在自動化設定畫面中點擊"檢視活動日誌"
- 檢視最近的自動化執行
- 檢查是否有錯誤或警告
- 驗證請求時間戳記和回應狀態
驗證資料格式
應用程式會自動在每個請求中包含以下標頭:
Content-Type- 根據匯出格式設定automation-name- 您的自動化名稱automation-id- 自動化的唯一識別碼automation-aggregation- 所選的時間分組automation-period- 所選的日期範圍session-id- 每個請求的唯一識別碼
疑難排解
常見問題
端點未收到資料
- 驗證端點 URL 是否正確
- 檢查您的端點是否接受 POST 請求
- 檢視身份驗證標頭
- 檢查端點的傳入請求日誌
- 驗證網路連線
提示和最佳實踐
效能:
- 使用適當的時間分組來平衡詳細資訊與資料大小
- 僅選擇您需要的指標
可靠性:
- 根據端點的回應時間設定適當的逾時值
- 定期監控活動日誌
資料格式:
- 對結構化資料和 API 使用 JSON
- 對簡單資料分析或試算表整合使用 CSV
- 考慮對大型資料集或單獨處理使用批次請求