Đồng bộ dữ liệu Apple Health lên Home Assistant

Tự động hóa Home Assistant cho phép bạn đồng bộ tự động dữ liệu sức khỏe lên Home Assistant dưới dạng trạng thái cảm biến. Tích hợp này giúp bạn dùng dữ liệu sức khỏe trong tự động hóa Home Assistant, bảng điều khiển và các tích hợp khác.

Tổng quan

Tự động hóa Home Assistant gửi chỉ số sức khỏe tới REST API của Home Assistant, tạo hoặc cập nhật trạng thái cảm biến dùng được trên toàn bộ phiên bản Home Assistant của bạn. Dữ liệu được định dạng riêng cho API /states/<entity_id> của Home Assistant.

Trường hợp sử dụng:

• Hiển thị chỉ số sức khỏe trên bảng điều khiển Home Assistant
• Tạo tự động hóa dựa trên dữ liệu sức khỏe
• Tích hợp dữ liệu sức khỏe với thiết bị nhà thông minh khác
• Theo dõi xu hướng sức khỏe theo thời gian trong Home Assistant

Tính năng chính:

• Tự động tạo trạng thái cảm biến
• Chỉ định dạng JSON (tối ưu cho Home Assistant)
• Chỉ loại dữ liệu Chỉ số sức khỏe
• Cấu hình URL đơn giản

Hạn chế

• Truy cập dữ liệu sức khỏe: Ứng dụng không được phép truy cập dữ liệu sức khỏe khi iPhone đang khóa. Tự động hóa chỉ chạy khi thiết bị được mở khóa. Có thể ảnh hưởng độ mới dữ liệu. Xem hướng dẫn đồng bộ thủ công.

• Xử lý nền: iOS giới hạn xử lý nền để tiết kiệm pin. Tự động hóa dựa vào Làm mới ứng dụng nền và có thể không chạy ngay nếu:

  • Làm mới ứng dụng nền bị tắt cho ứng dụng
  • Thiết bị ở chế độ nguồn điện thấp
  • Thiết bị không hoạt động trong thời gian dài
  • Tài nguyên hệ thống bị hạn chế
  • Nhiều ứng dụng tranh thời gian chạy nền

• Chỉ hỗ trợ loại dữ liệu Chỉ số sức khỏe

• Chỉ định dạng JSON (không đổi được)

Điều kiện cần

• Phiên bản Home Assistant đang chạy và truy cập được trên mạng của bạn
• Mã truy cập API Home Assistant (Long-Lived Access Token)
• Kết nối mạng tới phiên bản Home Assistant
• Phiên bản Home Assistant hỗ trợ REST API

Cấu hình

Vào màn hình Xuất tự động từ điều hướng chính, sau đó chạm « Tự động hóa mới » và chọn « Home Assistant » làm Loại tự động hóa.

Tên tự động hóa

Nhập tên mô tả cho tự động hóa. Tên này dùng để tạo mã thực thể cảm biến trong Home Assistant.

Lưu ý: Tên sẽ được chuyển thành chữ thường, bỏ khoảng trắng để tạo mã thực thể. Ví dụ: « My Health Data » thành hae.myhealthdata.

Thông báo

Cấu hình khi nhận thông báo:

• Thông báo khi cập nhật bộ nhớ đệm — Khi dữ liệu bộ nhớ đệm được cập nhật
• Thông báo khi chạy — Mỗi lần tự động hóa thực thi

URL Home Assistant

Nhập URL cơ sở của phiên bản Home Assistant. Gồm giao thức và cổng nếu không dùng mặc định.

Ví dụ URL:

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

Lưu ý: URL phải truy cập được từ thiết bị của bạn. Nếu dùng HTTPS, đảm bảo chứng chỉ hợp lệ hoặc thêm ngoại lệ.

Điểm cuối tự tạo

Ứng dụng tự tạo đầy đủ điểm cuối API dựa trên tên tự động hóa:

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

Ví dụ URL là http://homeassistant.local:8123 và tên tự động hóa là « Health Metrics », điểm cuối sẽ là:

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

Điểm cuối hiển thị bên dưới trường URL để tham khảo.

Thời gian chờ yêu cầu

Chọn khoảng thời gian chờ cho yêu cầu HTTP tới Home Assistant.

Tùy chọn thời gian chờ:

• 60 giây — Mặc định, phù hợp hầu hết phiên bản
• 300 giây (5 phút) — Khi Home Assistant chậm hơn
• 1800 giây (30 phút) — Xử lý rất chậm
• 3600 giây (1 giờ) — Tối đa khuyến nghị

Tiêu đề HTTP

Thêm tiêu đề xác thực cho API Home Assistant. Cần tiêu đề Authorization với Long-Lived Access Token.

Tiêu đề bắt buộc:

• Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN

Để lấy Long-Lived Access Token:

1. Mở Home Assistant
2. Vào hồ sơ (chạm tên ở góc dưới bên trái)
3. Cuộn tới « Long-Lived Access Tokens »
4. Chạm « Create Token »
5. Đặt tên (ví dụ: « Health Auto Export »)
6. Sao chép mã và dán vào trường giá trị tiêu đề

Tiêu đề tùy chọn:
Có thể thêm tiêu đề khác nếu cấu hình yêu cầu.

Cách thêm:

1. Chạm « Add Headers »
2. Nhập khóa tiêu đề bên trái
3. Nhập giá trị bên phải
4. Lặp cho tiêu đề bổ sung

Quan trọng: Mỗi khóa phải có giá trị tương ứng. Tiêu đề trống sẽ bị bỏ qua.

Cài đặt loại dữ liệu

Loại dữ liệu

Lưu ý: Tự động hóa Home Assistant chỉ hỗ trợ Chỉ số sức khỏe. Không đổi được và tự đặt thành Chỉ số sức khỏe.

Cấu hình Chỉ số sức khỏe

Chọn chỉ số sức khỏe — Chọn chỉ số cần gồm. Có thể chọn tất cả hoặc một phần.

Mẹo: Chỉ chọn chỉ số cần giúp giảm thời gian xử lý và kích thước dữ liệu gửi tới Home Assistant.

Nguồn ưu tiên — Cấu hình nguồn ưu tiên khi nhiều nguồn cùng một chỉ số.

Cài đặt xuất

Định dạng xuất

Lưu ý: Chỉ hỗ trợ JSON. Không đổi được và tự đặt JSON.

Phiên bản xuất

Lưu ý: Không có Phiên bản xuất cho Home Assistant vì định dạng tối ưu cho API trạng thái.

Khoảng ngày

Chọn khi xuất dữ liệu:

• Mặc định — Đồng bộ cả ngày hôm trước và dữ liệu tới thời điểm hiện tại
• Hôm nay — Tất cả dữ liệu trong ngày hiện tại tới thời điểm hiện tại
• Hôm qua — Toàn bộ ngày hôm trước

Lưu ý: Không hỗ trợ « Thời gian thực », « Kể từ lần đồng bộ trước » hoặc « 7 ngày trước ».

Tóm tắt dữ liệu

Bật hoặc tắt Tóm tắt dữ liệu cho Chỉ số sức khỏe.

• Bật — Tóm tổng hợp (mặc định)
• Tắt — Dữ liệu chi tiết từng điểm khi có thể

Lưu ý: Chỉ áp dụng cho loại Chỉ số sức khỏe.

Gom nhóm thời gian

Khi Tóm tắt dữ liệu bật, chọn cách gom:

• Mặc định — Không gom, điểm thô
• Ngày — Gom theo ngày (khuyến nghị)

Chu kỳ đồng bộ

Cấu hình tần suất đồng bộ dữ liệu lên Home Assistant:

Chọn một số và một khoảng thời gian.

Kiểm thử và xác minh

Kiểm thử thủ công

1. Chạm « Xuất thủ công » trên màn hình cấu hình
2. Chọn khoảng ngày
3. Chạm « Xuất » để gửi yêu cầu thử
4. Kiểm tra Home Assistant để xác nhận trạng thái cảm biến đã tạo/cập nhật

Xác minh trong Home Assistant

1. Mở Home Assistant
2. Vào Developer Tools > States
3. Tìm hae.{your_automation_name} (chữ thường, không khoảng trắng)
4. Xác nhận trạng thái cảm biến hiển thị dữ liệu sức khỏe
5. Kiểm tra « Last Updated » để xác nhận đồng bộ gần đây

Xem nhật ký hoạt động

1. Chạm « Xem nhật ký hoạt động » trên màn hình cấu hình
2. Xem các lần chạy gần đây
3. Kiểm tra lỗi hoặc cảnh báo
4. Xác minh thời điểm yêu cầu và trạng thái phản hồi

Kiểm tra nhật ký Home Assistant

Nếu không thấy dữ liệu:

1. Mở Home Assistant
2. Vào Settings > System > Logs
3. Tìm lỗi liên quan REST API hoặc trạng thái cảm biến
4. Kiểm tra lỗi xác thực hoặc định dạng dữ liệu không hợp lệ

Khắc phục sự cố

Sự cố thường gặp

Lỗi xác thực

• Kiểm tra Long-Lived Access Token đúng
• Tiêu đề Authorization đúng dạng: Bearer YOUR_TOKEN
• Mã chưa hết hạn hoặc bị thu hồi
• Mã có đủ quyền trong Home Assistant

Không thấy cảm biến trong Home Assistant

• Tên tự động hóa không chứa ký tự đặc biệt gây lỗi
• Định dạng mã thực thể: hae.{automation_name} (chữ thường, không khoảng trắng)
• Xem nhật ký Home Assistant
• Đảm bảo yêu cầu API thành công (xem Nhật ký hoạt động)

Dữ liệu không cập nhật

• Tự động hóa đang bật
• Xem Nhật ký hoạt động
• Kết nối mạng tới Home Assistant

Hết thời gian chờ kết nối

• Home Assistant đang chạy và truy cập được
• Kiểm tra mạng
• Tăng Thời gian chờ yêu cầu nếu phản hồi chậm
• Kiểm tra URL và cổng

Thông báo lỗi

Ứng dụng hiển thị lỗi nếu:

• URL không hợp lệ hoặc không tới được
• Xác thực thất bại (kiểm tra tiêu đề Authorization)
• Home Assistant trả mã lỗi
• Không có kết nối mạng

Xem Nhật ký hoạt động để biết chi tiết, gồm mã HTTP và thông báo từ Home Assistant.

Mẹo tích hợp Home Assistant

Dùng dữ liệu sức khỏe trong tự động hóa

Sau khi đồng bộ, bạn có thể dùng trong tự động hóa:

automation:
  - alias: "Good Sleep Quality"
    trigger:
      - platform: numeric_state
        entity_id: sensor.hae_myhealthdata_sleep_total
        above: 7
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "Great sleep last night!"

Tạo bảng điều khiển

Thêm chỉ số sức khỏe vào bảng điều khiển:

1. Vào bảng điều khiển
2. Thêm thẻ mới
3. Chọn loại thẻ « Entities » hoặc « Gauge »
4. Thêm thực thể cảm biến hae.{your_automation_name}

Cấu trúc trạng thái cảm biến

Trạng thái cảm biến trong Home Assistant gồm:

• state: Giá trị hoặc trạng thái hiện tại
• attributes: Dữ liệu bổ sung gồm:
  • Thông tin thời gian
  • Cấu trúc khớp JSON xuất
  • Đơn vị khi có

Mẹo và thực hành tốt

1. Đồng bộ tự động:

   • Sạc thiết bị và dùng iPhone Mirroring
     • Khi sạc, iOS hạn chế hiệu năng ít hơn nên đồng bộ thường xuyên hơn
     • iPhone Mirroring khiến thiết bị như đang mở khóa, dữ liệu sức khỏe có thể truy cập để chạy tự động hóa

2. Đặt tên:

   • Tránh ký tự đặc biệt gây lỗi

3. Lựa chọn dữ liệu:

   • Chỉ chọn chỉ số cần thiết