將 Apple Health 資料同步到 MQTT

MQTT 自動化允許您自動將健康資料發佈到 MQTT 代理。這對於與 IoT 平台、家庭自動化系統或任何支援 MQTT 訊息傳遞的服務整合非常理想。

概述

MQTT 自動化將您的健康資料作為 JSON 訊息發佈到 MQTT 代理上的指定 MQTT 主題。資料會根據您的同步頻率設定，在自動化執行時傳送。

使用場景:

• 與 IoT 平台整合（Home Assistant、OpenHAB 等）
• 將健康資料發佈到基於 MQTT 的儀表板
• 即時健康監控系統
• 自訂家庭自動化整合
• 資料記錄和分析平台

主要功能:

• 僅支援 JSON 格式（針對 MQTT 最佳化）
• 支援已認證和匿名連線
• 可設定的主題結構
• 用戶端 ID 管理
• 可選的使用者名稱/密碼認證

限制

• 健康資料存取: iPhone 鎖定時，應用程式不允許存取健康資料。自動化僅在裝置解鎖期間執行。這可能會影響資料的新鮮度。請參閱手動同步說明以保持資料最新。

• 背景處理: iOS 限制背景處理以保持電池壽命。自動化依賴於背景應用程式重新整理，在以下情況下可能不會立即執行:

  • 應用程式的背景應用程式重新整理已停用
  • 裝置處於低電量模式
  • 裝置長時間處於非活動狀態
  • 系統資源受限
  • 多個應用程式競爭背景執行時間

• 僅支援 JSON 格式（無法變更）

• 需要 MQTT 代理（本機或基於雲端）

先決條件

• MQTT 代理（例如 Mosquitto、HiveMQ、AWS IoT Core 等）
• 與 MQTT 代理的網路連線
• 代理 IP 位址或主機名稱
• 連接埠號碼
• 選用: 如果代理需要認證，則提供使用者名稱和密碼

設定

從主導覽移至自動匯出畫面，然後點選「新增自動化」並選擇「MQTT」作為自動化類型。

自動化名稱

輸入自動化的描述性名稱（例如「Home Assistant MQTT」、「雲端 MQTT 代理」）。

通知

設定何時接收通知:

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

代理設定

IP 位址

輸入 MQTT 代理的 IP 位址或主機名稱。

範例:

• 192.168.1.100（本機 IP 位址）
• mqtt.example.com（主機名稱）
• broker.hivemq.com（雲端 MQTT 代理）
• localhost（如果在同一裝置上執行，不建議用於 iOS）

注意: 對於網路上的本機代理使用 IP 位址，對於基於雲端的代理使用主機名稱。確保代理可以從您的裝置存取。

連接埠

輸入 MQTT 代理的連接埠號碼。

注意: 預設連接埠是 1883。

主題

輸入將發佈健康資料的 MQTT 主題。這是訂閱者將用於接收您的健康資料的主題。

主題範例:

• health/data
• home/health/metrics
• user/health/export
• hae/automation-name

主題最佳實務:

• 使用正斜線（/）建立主題階層結構
• 使用指示資料類型的描述性名稱
• 避免空格和特殊字元
• 考慮為多個自動化包含自動化名稱

注意: 主題名稱區分大小寫。確保訂閱者使用完全相同的主題名稱。

用戶端 ID

輸入此 MQTT 連線的唯一用戶端 ID。這會將您的裝置識別給 MQTT 代理。

用戶端 ID 範例:

• health-export-iphone
• hae-client-001
• ios-health-app

使用者名稱（選用）

輸入 MQTT 代理認證的使用者名稱。如果代理不需要認證，請留空。

密碼（選用）

輸入 MQTT 代理認證的密碼。如果代理不需要認證，請留空。

資料類型設定

資料類型

選擇要匯出的健康資料類型:

• 健康指標 - 步數、心率、睡眠和其他健康測量值
• 鍛鍊 - 運動和健身活動
• 症狀 - 健康症狀和狀況
• 心電圖 - 心電圖讀數
• 心率通知 - 高/低心率事件
• 心理狀態 - 情緒和心理狀態項目（iOS 18.0+）
• 週期追蹤 - 月經週期和生殖健康資料
• 藥物 - 藥物記錄和依從性（iOS 26.0+）

健康指標設定

選擇健康指標時:

選擇健康指標 - 選擇要包含的特定指標。您可以選擇所有可用指標或選擇特定指標。

提示: 僅選擇所需的指標可減少訊息大小和處理時間。

首選來源 - 設定當多個來源提供相同指標時哪些資料來源優先。

鍛鍊設定

選擇鍛鍊時:

包含路線資料 - 切換為開啟以包含具有位置資料的鍛鍊路線。

包含鍛鍊指標 - 切換為開啟以包含鍛鍊期間收集的健康指標（心率、卡路里等）。

時間分組（鍛鍊指標） - 使用匯出版本 2 且啟用包含鍛鍊指標時:

• 分鐘 - 按分鐘分組鍛鍊指標
• 秒 - 按秒分組鍛鍊指標

匯出設定

匯出格式

注意: MQTT 自動化僅支援 JSON 格式。此設定無法變更，會自動設定為 JSON。

匯出版本

為鍛鍊資料選擇匯出版本:

• 版本 1 - 舊格式
• 版本 2 - 具有增強鍛鍊資料的目前格式

注意: 匯出版本主要影響鍛鍊資料結構（如果您正在匯出鍛鍊）。

日期範圍

選擇何時匯出資料:

• 預設 - 同步前一天的完整資料加上目前日期和時間之前的資料
• 自上次同步 - 每次同步時，匯出自上次匯出執行以來直到目前日期和時間的所有資料
• 今天 - 同步目前日期到目前時間的所有資料
• 昨天 - 同步前一天的完整所有資料
• 過去 7 天 - 同步過去七天的完整資料

彙總資料

使用 JSON 格式和健康指標資料類型時，切換彙總資料開啟或關閉。

• 開啟 - 提供彙總資料摘要（預設）
• 關閉 - 盡可能提供非彙總資料，顯示個別資料點

時間分組

啟用彙總資料時，選擇應如何彙總資料。

彙總資料

為健康指標切換彙總資料開啟或關閉。

• 開啟 - 提供彙總資料摘要（預設）
• 關閉 - 盡可能提供非彙總資料

注意: 此設定僅適用於健康指標資料類型。

同步頻率

設定自動化應多久向 MQTT 發佈一次資料:

選擇一個數字和間隔。

測試和驗證

手動測試

1. 在自動化設定畫面中點選「手動匯出」
2. 選擇日期範圍
3. 點選「匯出」以發佈訊息
4. 使用 MQTT 用戶端訂閱您的主題並驗證訊息已接收

使用 MQTT 用戶端

要驗證訊息正在發佈:

1. 設定 MQTT 用戶端
2. 使用相同的憑證連線到 MQTT 代理
3. 訂閱您的主題
4. 從應用程式觸發手動匯出
5. 驗證訊息出現在 MQTT 用戶端中

檢視活動記錄

1. 在自動化設定畫面中點選「檢視活動記錄」
2. 檢視最近的自動化執行
3. 檢查連線錯誤或發佈失敗
4. 驗證發佈時間戳記

訊息格式

MQTT 訊息以 JSON 格式發佈。訊息承載遵循標準匯出 JSON 格式:

{
  "data": {
    "metrics": [...],
    "workouts": [...],
    ...
  }
}

訊息發佈時包含:

• 主題: 在自動化中設定的主題
• QoS: 最多一次傳遞
• 保留: 訊息不保留
• 承載: 包含健康資料的 JSON 字串

疑難排解

常見問題

連線失敗

• 驗證代理 IP 位址/主機名稱是否正確
• 檢查連接埠是否正確以及代理是否在該連接埠上監聽
• 確保與代理的網路連線
• 驗證防火牆規則允許連線到代理
• 檢查代理是否需要 TLS/SSL

認證失敗

• 驗證使用者名稱和密碼是否正確
• 如果提供了憑證，檢查代理上是否啟用了認證
• 確保使用者有權發佈到指定主題

未收到訊息

• 驗證主題名稱是否完全匹配（區分大小寫）
• 檢查訂閱者是否連線到同一代理
• 確保訂閱者訂閱了正確的主題
• 驗證自動化已啟用並正在執行
• 檢查活動記錄中的發佈錯誤

訊息大小過大

• 減少所選健康指標的數量
• 使用不太細粒度的彙總選項
• 考慮為不同的資料類型拆分為多個自動化

提示和最佳實務

1. 主題組織:

   • 使用階層式主題結構（例如 health/metrics、health/workouts）
   • 在主題中包含裝置或自動化識別碼
   • 記錄您的主題結構以便於參考

2. 訊息大小:

   • 保持訊息大小合理以避免 MQTT 代理限制
   • 使用不太細粒度的彙總以減少資料量
   • 考慮將大型資料集拆分為多個訊息

3. 監控:

   • 使用應用程式中的活動記錄追蹤發佈成功

4. 雲端代理:

   • 使用雲端 MQTT 代理（AWS IoT、HiveMQ Cloud 等）時:
     • 遵循其特定的連線要求
     • 檢查其訊息大小和速率限制
     • 驗證主題命名慣例