Apple Health 데이터를 MQTT에 동기화

건강 데이터를 MQTT 브로커에 게시합니다.

Last updated: February 5, 2026

On this page

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 브로커 인증을 위한 비밀번호를 입력합니다. 브로커가 인증을 요구하지 않는 경우 비워 둡니다.

데이터 유형 설정

데이터 유형

내보낼 건강 데이터 유형을 선택합니다:

건강 메트릭 - 걸음 수, 심박수, 수면 및 기타 건강 측정값
운동 - 운동 및 피트니스 활동
증상 - 건강 증상 및 상태
ECG - 심전도 판독값
심박수 알림 - 높음/낮음 심박수 이벤트
마음 상태 - 기분 및 정신 상태 항목 (iOS 18.0+)
주기 추적 - 월경 주기 및 생식 건강 데이터
약물 - 약물 로그 및 순응도 (iOS 26.0+)

건강 메트릭 구성

건강 메트릭이 선택된 경우:

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

팁: 필요한 메트릭만 선택하면 메시지 크기와 처리 시간이 줄어듭니다.

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

운동 구성

운동이 선택된 경우:

경로 데이터 포함 - 위치 데이터가 있는 운동의 경로를 포함하려면 켜기로 설정합니다.

운동 메트릭 포함 - 운동 중 수집된 건강 메트릭(심박수, 칼로리 등)을 포함하려면 켜기로 설정합니다.

시간 그룹화 (운동 메트릭) - 내보내기 버전 2를 사용하고 운동 메트릭 포함이 활성화된 경우:

분 - 운동 메트릭을 분별로 그룹화
초 - 운동 메트릭을 초별로 그룹화

내보내기 설정

내보내기 형식

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

내보내기 버전

운동 데이터에 대한 내보내기 버전을 선택합니다:

버전 1 - 레거시 형식
버전 2 - 향상된 운동 데이터가 있는 현재 형식

참고: 내보내기 버전은 운동을 내보내는 경우 주로 운동 데이터 구조에 영향을 줍니다.

날짜 범위

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

기본값 - 이전 날의 전체 데이터와 현재 날짜 및 시간까지의 데이터 동기화
마지막 동기화 이후 - 각 동기화에서 마지막으로 내보내기가 실행된 시점부터 현재 날짜 및 시간까지의 모든 데이터 내보내기
오늘 - 현재 날짜의 현재 시간까지의 모든 데이터 동기화
어제 - 이전 날의 전체 모든 데이터 동기화
이전 7일 - 이전 7일의 전체 데이터 동기화

데이터 요약

건강 메트릭 데이터 유형과 함께 JSON 형식을 사용하는 경우 데이터 요약을 켜기 또는 끄기로 설정합니다.

켜기 - 집계된 데이터 요약 제공 (기본값)
끄기 - 가능한 경우 비집계 데이터 제공, 개별 데이터 포인트 표시

시간 그룹화

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

데이터 요약

건강 메트릭에 대해 데이터 요약을 켜기 또는 끄기로 설정합니다.

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

참고: 이 설정은 건강 메트릭 데이터 유형에만 적용됩니다.

동기화 주기

자동화가 MQTT에 데이터를 게시하는 빈도를 구성합니다:

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

테스트 및 확인

수동 테스트

자동화 구성 화면에서 "수동 내보내기" 탭
날짜 범위 선택
"내보내기"를 탭하여 메시지 게시
MQTT 클라이언트를 사용하여 토픽을 구독하고 메시지가 수신되었는지 확인

MQTT 클라이언트 사용

메시지가 게시되고 있는지 확인하려면:

MQTT 클라이언트 설정
동일한 자격 증명을 사용하여 MQTT 브로커에 연결
토픽 구독
앱에서 수동 내보내기 트리거
메시지가 MQTT 클라이언트에 나타나는지 확인

활동 로그 보기

자동화 구성 화면에서 "활동 로그 보기" 탭
최근 자동화 실행 검토
연결 오류 또는 게시 실패 확인
게시 타임스탬프 확인

메시지 형식

MQTT 메시지는 JSON으로 게시됩니다. 메시지 페이로드는 표준 내보내기 JSON 형식을 따릅니다:

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

메시지는 다음으로 게시됩니다:

토픽: 자동화에서 구성된 대로
QoS: 최대 한 번 전달
유지: 메시지는 유지되지 않음
페이로드: 건강 데이터를 포함하는 JSON 문자열

문제 해결

일반적인 문제

연결 실패

브로커 IP 주소/호스트 이름이 올바른지 확인
포트가 올바르고 브로커가 해당 포트에서 수신 중인지 확인
브로커에 대한 네트워크 연결 확인
방화벽 규칙이 브로커에 대한 연결을 허용하는지 확인
브로커가 TLS/SSL을 요구하는지 확인

인증 실패

사용자 이름과 비밀번호가 올바른지 확인
자격 증명이 제공된 경우 브로커에서 인증이 활성화되어 있는지 확인
사용자가 지정된 토픽에 게시할 권한이 있는지 확인

메시지 수신 안 됨

토픽 이름이 정확히 일치하는지 확인 (대소문자 구분)
구독자가 같은 브로커에 연결되어 있는지 확인
구독자가 올바른 토픽을 구독하고 있는지 확인
자동화가 활성화되어 실행 중인지 확인
게시 오류에 대한 활동 로그 확인

큰 메시지 크기

선택된 건강 메트릭 수 줄이기
덜 세분화된 집계 옵션 사용
다른 데이터 유형에 대해 여러 자동화로 분할 고려

팁 및 모범 사례

토픽 구성:
- 계층적 토픽 구조 사용 (예: health/metrics, health/workouts)
- 토픽에 기기 또는 자동화 식별자 포함
- 쉬운 참조를 위해 토픽 구조 문서화
메시지 크기:
- MQTT 브로커 제한을 피하기 위해 메시지를 합리적인 크기로 유지
- 데이터 볼륨을 줄이기 위해 덜 세분화된 집계 사용
- 큰 데이터 세트를 여러 메시지로 분할 고려
모니터링:
- 앱의 활동 로그를 사용하여 게시 성공 추적
클라우드 브로커:
- 클라우드 MQTT 브로커(AWS IoT, HiveMQ Cloud 등)를 사용하는 경우:
  - 특정 연결 요구 사항 준수
  - 메시지 크기 및 속도 제한 확인
  - 토픽 명명 규칙 확인