HealthyApps Help Center

將 Apple Health 資料同步到 Home Assistant

將您的健康資料與 Home Assistant 整合。

Last updated: February 5, 2026

On this page

Home Assistant 自動化允許您將健康資料自動同步到 Home Assistant 作為感測器狀態。此整合使您能夠在 Home Assistant 自動化、儀表板和其他整合中使用您的健康資料。

概述

Home Assistant 自動化將您的健康指標發送到 Home Assistant 的 REST API，建立或更新可在整個 Home Assistant 執行個體中使用的感測器狀態。資料專門為 Home Assistant 的 /states/ API 格式化。

使用場景:

  • 在 Home Assistant 儀表板上顯示健康指標
  • 基於健康資料建立自動化
  • 將健康資料與其他智慧家居裝置整合
  • 在 Home Assistant 中追蹤健康趨勢

主要功能:

  • 自動感測器狀態建立
  • 僅 JSON 格式（針對 Home Assistant 最佳化）
  • 僅支援 Health Metrics 資料類型
  • 簡單的 URL 設定

限制

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

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

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

  • 僅支援 Health Metrics 資料類型

  • 僅 JSON 格式（無法變更）

先決條件

  • 在您的網路上執行且可存取的 Home Assistant 執行個體
  • Home Assistant API 存取權杖（長期存取權杖）
  • 到您的 Home Assistant 執行個體的網路連線
  • 支援 REST API 的 Home Assistant 版本

設定

從主導覽導航到自動化匯出畫面，然後點選「新增自動化」並選擇「Home Assistant」作為自動化類型。

自動化名稱

為您的自動化輸入一個描述性名稱。此名稱將用於在 Home Assistant 中產生感測器實體 ID。

注意: 自動化名稱將轉換為小寫並刪除空格以建立實體 ID。例如，「我的健康資料」變為 hae.wodejiankangziliao。

通知

設定何時接收通知:

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

Home Assistant URL

輸入您的 Home Assistant 執行個體的基本 URL。如果不使用預設值，則應包括通訊協定和連接埠。

URL 範例:

  • http://homeassistant.local:8123
  • http://192.168.1.100:8123

注意: URL 必須可從您的裝置存取。如果使用 HTTPS，請確保您的憑證有效或新增例外。

自動產生的端點

應用程式會根據您的自動化名稱自動產生完整的 API 端點:

{your_url}/api/states/hae.{automation_name}

例如，如果您的 URL 是 http://homeassistant.local:8123 且您的自動化名稱是「健康指標」，則端點將是:

http://homeassistant.local:8123/api/states/hae.jiankangzhibiao

此端點顯示在 URL 欄位下方作為參考。

請求逾時

選擇對 Home Assistant 的 HTTP 請求的逾時間隔。

可用的逾時選項:

  • 60 秒 - 預設值，適用於大多數 Home Assistant 執行個體
  • 300 秒（5 分鐘） - 適用於較慢的 Home Assistant 執行個體
  • 1800 秒（30 分鐘） - 適用於非常慢的處理
  • 3600 秒（1 小時） - 最大建議逾時

HTTP 標頭

新增用於存取 Home Assistant API 的身分驗證標頭。您需要使用長期存取權杖新增 Authorization 標頭。

必要標頭:

  • Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN

要取得長期存取權杖:

  1. 開啟 Home Assistant
  2. 前往您的個人資料（點選左下角的您的姓名）
  3. 向下捲動到「長期存取權杖」
  4. 點選「建立權杖」
  5. 給它一個名稱（例如，「Health Auto Export」）
  6. 複製權杖並將其貼上到標頭值欄位中

選用標頭:
如果需要，您可以為 Home Assistant 設定新增其他標頭。

要新增標頭:

  1. 點選「新增標頭」
  2. 在左側欄位中輸入標頭鍵
  3. 在右側欄位中輸入標頭值
  4. 對其他標頭重複

重要: 每個標頭鍵必須具有對應的值。空標頭將被忽略。

資料類型設定

資料類型

注意: Home Assistant 自動化僅支援 Health Metrics 資料類型。此設定無法變更，並自動設定為 Health Metrics。

Health Metrics 設定

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

提示: 僅選擇您需要的指標可以改善處理時間並減少發送到 Home Assistant 的資料大小。

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

匯出設定

匯出格式

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

匯出版本

注意: 匯出版本不適用於 Home Assistant 自動化，因為格式專門針對 Home Assistant 的狀態 API 進行了最佳化。

日期範圍

選擇何時應匯出資料:

  • 預設 - 同步前一天的全部資料加上到目前日期和時間的資料
  • 今天 - 同步目前日期到目前時間的所有資料
  • 昨天 - 同步前一天的全部所有資料

注意: Home Assistant 自動化不支援「即時」、「自上次同步」或「過去 7 天」選項。

彙總資料

為 Health Metrics 開啟或關閉彙總資料。

  • 開啟 - 提供彙總資料摘要（預設）
  • 關閉 - 在可能的情況下提供非彙總資料

注意: 此設定僅適用於 Health Metrics 資料類型。

時間分組

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

  • 預設 - 無彙總，原始資料點
  • 天 - 按天分組資料（建議）

同步頻率

設定自動化應多久與 Home Assistant 同步資料:

選擇一個數字和間隔。

測試和驗證

手動測試

  1. 在自動化設定畫面上點選「手動匯出」
  2. 選擇日期範圍
  3. 點選「匯出」以發送測試請求
  4. 在 Home Assistant 中檢查感測器狀態是否已建立/更新

在 Home Assistant 中驗證

  1. 開啟 Home Assistant
  2. 前往開發人員工具 > 狀態
  3. 搜尋 hae.{your_automation_name}（小寫，無空格）
  4. 驗證感測器狀態顯示您的健康資料
  5. 檢查「最後更新」時間戳記以確認最近的同步

檢視活動記錄

  1. 在自動化設定畫面上點選「檢視活動記錄」
  2. 檢視最近的自動化執行
  3. 檢查是否有錯誤或警告
  4. 驗證請求時間戳記和回應狀態

檢查 Home Assistant 記錄

如果資料未出現在 Home Assistant 中:

  1. 開啟 Home Assistant
  2. 前往設定 > 系統 > 記錄
  3. 尋找與 REST API 或感測器狀態相關的錯誤
  4. 檢查身分驗證錯誤或無效資料格式

疑難排解

常見問題

身分驗證錯誤

  • 驗證您的長期存取權杖是否正確
  • 確保 Authorization 標頭格式為: Bearer YOUR_TOKEN
  • 檢查權杖是否已過期或已被撤銷
  • 驗證權杖在 Home Assistant 中具有適當的權限

感測器未出現在 Home Assistant 中

  • 檢查自動化名稱是否包含特殊字元
  • 驗證實體 ID 格式: hae.{automation_name}（小寫，無空格）
  • 檢查 Home Assistant 記錄中的錯誤
  • 確保 API 請求成功（檢查活動記錄）

資料未更新

  • 檢查自動化是否已啟用
  • 檢視活動記錄中的錯誤
  • 確保與 Home Assistant 的網路連線

連線逾時

  • 驗證 Home Assistant 是否正在執行且可存取
  • 檢查網路連線
  • 如果 Home Assistant 回應緩慢，請增加請求逾時設定
  • 驗證 URL 和連接埠是否正確

錯誤訊息

如果出現以下情況，應用程式將顯示錯誤訊息:

  • URL 無效或無法存取
  • 身分驗證失敗（檢查 Authorization 標頭）
  • Home Assistant 傳回錯誤狀態代碼
  • 網路連線不可用

檢查活動記錄以取得詳細的錯誤資訊，包括 HTTP 狀態代碼和來自 Home Assistant 的錯誤訊息。

Home Assistant 整合提示

在自動化中使用健康資料

健康資料與 Home Assistant 同步後，您可以在自動化中使用它們:

automation:
  - alias: "良好睡眠品質"
    trigger:
      - platform: numeric_state
        entity_id: sensor.hae_myhealthdata_sleep_total
        above: 7
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "昨晚睡眠很棒！"

建立儀表板

將健康指標新增到您的 Home Assistant 儀表板:

  1. 前往您的儀表板
  2. 新增新卡片
  3. 選擇「實體」或「儀表」卡片類型
  4. 新增 hae.{your_automation_name} 感測器實體

感測器狀態結構

Home Assistant 中的感測器狀態包含:

  • state: 目前值或狀態
  • attributes: 其他資料包括:
    • 時間戳記資訊
    • 與匯出的 JSON 格式匹配的資料結構
    • 適用時的單位資訊

提示和最佳實踐

  1. 命名:

    • 避免可能導致問題的特殊字元

  2. 資料選擇:

    • 僅選擇您需要的指標