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.naegeonangdeiteo가 됩니다.

알림

알림을 받을 시기를 구성합니다:

캐시 업데이트 시 알림 - 캐시된 데이터가 업데이트될 때 알림 받기
실행 시 알림 - 자동화가 실행될 때마다 알림 받기

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.geonangmeteulig

이 엔드포인트는 참조용으로 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

장기 액세스 토큰을 얻으려면:

Home Assistant 열기
프로필로 이동 (왼쪽 하단의 이름 클릭)
"장기 액세스 토큰"까지 스크롤
"토큰 만들기" 클릭
이름 지정 (예: "Health Auto Export")
토큰을 복사하여 헤더 값 필드에 붙여넣기

선택적 헤더:
Home Assistant 설정에 필요한 경우 추가 헤더를 추가할 수 있습니다.

헤더를 추가하려면:

"헤더 추가" 탭
왼쪽 필드에 헤더 키 입력
오른쪽 필드에 헤더 값 입력
추가 헤더에 대해 반복

중요: 각 헤더 키에는 해당 값이 있어야 합니다. 빈 헤더는 무시됩니다.

데이터 유형 설정

데이터 유형

참고: Home Assistant 자동화는 Health Metrics 데이터 유형만 지원합니다. 이 설정은 변경할 수 없으며 자동으로 Health Metrics로 설정됩니다.

Health Metrics 구성

Health Metrics 선택 - 포함할 특정 메트릭을 선택합니다. 사용 가능한 모든 메트릭을 선택하거나 특정 메트릭을 선택할 수 있습니다.

팁: 필요한 메트릭만 선택하면 처리 시간을 개선하고 Home Assistant로 전송되는 데이터 크기를 줄일 수 있습니다.

선호 소스 - 여러 소스가 동일한 메트릭을 제공할 때 어떤 데이터 소스에 우선순위를 둘지 구성합니다.

내보내기 설정

내보내기 형식

참고: Home Assistant 자동화는 JSON 형식만 지원합니다. 이 설정은 변경할 수 없으며 자동으로 JSON으로 설정됩니다.

내보내기 버전

참고: 내보내기 버전은 형식이 Home Assistant의 상태 API에 맞게 특별히 최적화되어 있으므로 Home Assistant 자동화에서는 사용할 수 없습니다.

날짜 범위

데이터를 내보낼 시기를 선택합니다:

기본값 - 이전 날의 전체 데이터와 현재 날짜 및 시간까지의 데이터 동기화
오늘 - 현재 날짜의 현재 시간까지의 모든 데이터 동기화
어제 - 이전 날의 전체 모든 데이터 동기화

참고: Home Assistant 자동화는 "실시간", "마지막 동기화 이후" 또는 "지난 7일" 옵션을 지원하지 않습니다.

데이터 요약

Health Metrics에 대해 데이터 요약을 켜거나 끕니다.

켜기 - 집계된 데이터 요약 제공 (기본값)
끄기 - 가능한 경우 비집계 데이터 제공

참고: 이 설정은 Health Metrics 데이터 유형에만 적용됩니다.

시간 그룹화

데이터 요약이 활성화된 경우 데이터를 집계하는 방법을 선택합니다:

기본값 - 집계 없음, 원시 데이터 포인트
일 - 일별로 데이터 그룹화 (권장)

동기화 빈도

자동화가 Home Assistant와 데이터를 동기화할 빈도를 구성합니다:

숫자와 간격을 선택합니다.

테스트 및 확인

수동 테스트

자동화 구성 화면에서 "수동 내보내기" 탭
날짜 범위 선택
"내보내기" 탭하여 테스트 요청 전송
Home Assistant에서 센서 상태가 생성/업데이트되었는지 확인

Home Assistant에서 확인

Home Assistant 열기
개발자 도구 > 상태로 이동
hae.{your_automation_name} (소문자, 공백 없음) 검색
센서 상태에 건강 데이터가 표시되는지 확인
"마지막 업데이트" 타임스탬프를 확인하여 최근 동기화 확인

활동 로그 보기

자동화 구성 화면에서 "활동 로그 보기" 탭
최근 자동화 실행 검토
오류 또는 경고 확인
요청 타임스탬프 및 응답 상태 확인

Home Assistant 로그 확인

데이터가 Home Assistant에 표시되지 않는 경우:

Home Assistant 열기
설정 > 시스템 > 로그로 이동
REST API 또는 센서 상태와 관련된 오류 찾기
인증 오류 또는 잘못된 데이터 형식 확인

문제 해결

일반적인 문제

인증 오류

장기 액세스 토큰이 올바른지 확인
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 대시보드에 건강 메트릭 추가:

대시보드로 이동
새 카드 추가
카드 유형 "엔티티" 또는 "게이지" 선택
hae.{your_automation_name} 센서 엔티티 추가

센서 상태 구조

Home Assistant의 센서 상태에는 다음이 포함됩니다:

state: 현재 값 또는 상태
attributes: 추가 데이터 포함:
- 타임스탬프 정보
- 내보낸 JSON 형식과 일치하는 데이터 구조
- 해당하는 경우 단위 정보

팁 및 모범 사례

명명:
- 문제를 일으킬 수 있는 특수 문자 피하기
데이터 선택:
- 필요한 메트릭만 선택