MQTT로 Apple Health 데이터 동기화
건강 데이터를 MQTT 브로커에 게시합니다.
최근 업데이트: 2026년 10월 31일
이 페이지에서
건강 내보내기를 JSON으로 MQTT 브로커의 토픽에 게시합니다.
중요 — 자동화 제한 사항: 건강 데이터를 읽으려면 기기가 잠금 해제되어 있어야 하며, iOS는 선택한 빈도로 백그라운드 실행을 보장하지 않습니다. 자동 내보내기에 의존하기 전에 자동화 제한 사항을 확인하세요.
자동화 열기
iPhone에서는 보내기 → 자동화를, iPad에서는 사이드바의 자동화를 엽니다. 새 자동화를 선택하거나 기존 자동화를 열어 편집합니다.
이름, 상태, 알림
이 자동화를 식별하는 이름을 입력합니다. 활성화는 자동 실행을 허용합니다. 준비될 때까지 꺼 두세요.
필요한 실행 알림을 선택합니다:
- 캐시 업데이트 시 알림은 내보내기 데이터 준비 완료를 보고합니다.
- 실행 시 알림은 브로커 게시 성공을 보고합니다.
요청되면 알림을 허용하세요. 이 알림은 활동만 보고하며 실행을 예약하지 않습니다.
연결 설정
- 자동화 유형으로 MQTT를 선택합니다.
- 브로커의 호스트 이름 또는 IP 주소와 포트를 입력합니다. 기본 포트는 1883입니다.
- 토픽을 입력합니다(예:
health/metrics). - 각 자동화에 고유한 클라이언트 ID를 설정하고, 브로커가 요구하면 사용자 이름과 비밀번호를 입력합니다.
브로커는 기기에서 도달 가능해야 합니다. 구독자는 대소문자를 포함해 정확한 토픽을 사용해야 합니다. 클라이언트 ID를 재사용하면 브로커 연결이 서로 대체될 수 있습니다.
데이터 유형 설정
이 자동화의 데이터 유형을 하나 선택합니다: 건강 지표, 운동, 증상, ECG, 심박수 알림, 마음 상태, 주기 추적 또는 약물. 마음 상태는 iOS 18 이상, 약물은 iOS 26 이상과 별도의 약물 액세스가 필요합니다.
건강 지표
건강 지표를 선택한 뒤 건강 지표 선택을 열어 필요한 측정값을 고릅니다.
특정 앱이나 기기의 측정값으로 제한하려면 선호 소스를 열고 지표를 고른 뒤 소스를 선택합니다. 모두는 제외되지 않은 모든 소스를 허용합니다. 제외된 소스로 이 자동화의 건강 지표 전체에서 소스를 무시할 수 있습니다. 제외가 우선합니다. 선호 소스에 데이터가 없어도 선택하지 않은 소스로 대체되지 않습니다. 저장으로 소스 선택을 적용하고 취소로 버립니다.
운동
운동을 선택하면 운동 기록을 내보냅니다. 경로 데이터 포함은 사용 가능한 경로 포인트를 JSON 운동 데이터에 추가합니다. 별도의 GPX 업로드는 만들지 않습니다.
버전 2에서는 운동 지표 포함을 켜 심박수, 활동 에너지, 걸음 수 같은 측정값을 추가합니다. 운동 지표 시간 그룹화에서 분 또는 초를 선택하세요. 초가 더 상세하고 내보내기가 커집니다. 버전 1은 항상 운동 지표를 포함합니다.
내보내기 설정
MQTT는 JSON만 게시합니다. 메시지는 포그라운드 게시에서 QoS 0, 백그라운드 게시에서 QoS 1을 사용합니다. 메시지는 유지되지 않습니다.
내보내기 버전
현재 데이터 구조에는 버전 2를 선택하세요. 기존 워크플로가 이전 형식에 의존하면 버전 1을 사용합니다.
날짜 범위
| 선택 | 포함 데이터 |
|---|---|
| 기본값 | 전일과 실행 시각까지의 오늘 |
| 마지막 동기화 이후 | 이전 동기화부터 실행 시각까지 |
| 오늘 | 실행 시각까지의 오늘 |
| 어제 | 직전 하루 전체 |
| 지난 7일 | 직전 7일 전체 |
데이터 요약 및 시간 그룹화
JSON + 건강 지표에서는 데이터 요약을 켜 측정값을 시간 그룹으로 합치거나, 지원되는 경우 꺼서 개별 측정값으로 둡니다. 요약은 지표에 따라 다릅니다. 예를 들어 걸음 수는 합산되고 체중 측정값은 평균됩니다. CSV 건강 지표 내보내기는 요약 데이터를 사용합니다.
시간 그룹화를 사용할 수 있으면 유지할 상세 수준을 선택하세요. 시간 또는 일 그룹은 분 또는 초 그룹보다 행이 적습니다. 사용 가능한 선택은 날짜 범위와 형식에 따라 다릅니다. 운동 시간 그룹화는 운동 설정에서 따로 구성합니다.
일정 알림
잠금 해제와 앱 열기 안내가 필요하면 알림 사용을 켭니다. 매시간, 매일 또는 선택한 요일을 고른 뒤 필요에 따라 분, 시각, 요일을 설정합니다. 요청되면 알림 액세스를 허용하고, 거부된 경우 알림 설정 열기를 사용하세요.
알림은 자동화를 실행하지 않으며 동기화 성공도 확인하지 않습니다. 탭해 자동화를 열거나 알림의 열고 동기화로 실행을 요청합니다. 자동화가 활성화되어 있어야 합니다. 성공한 백그라운드 실행 후에도 알림이 나타날 수 있습니다. 알림 변경은 저장 시 적용됩니다.
동기화 빈도 및 저장
동기화 빈도에서 숫자와 분, 시간, 일 또는 주를 선택합니다(예: 15분마다). 이는 원하는 백그라운드 주기이며 보장된 일정이 아닙니다.
건강 데이터를 읽을 때 기기는 잠금 해제되어 있어야 합니다. Health Auto Export의 백그라운드 앱 새로 고침을 켜고 자동 실행을 위해 저전력 모드를 끄세요. 기기가 비활성 상태였거나 시스템 리소스가 제한되면 iOS가 실행을 지연할 수 있습니다.
자동 실행 준비가 되면 활성화를 켠 뒤 업데이트로 자동화를 저장합니다. 아래 단계로 선택한 날짜 범위를 바로 업로드할 수 있습니다.
기록 또는 놓친 데이터 내보내기
자동화 최초 설정 시 기록 데이터를 내보내거나, 나중에 자동 동기화에서 놓친 날짜를 채우기 위해 수동 업로드를 사용합니다. 설정 확인에도 사용할 수 있습니다.
- MQTT 구독자를 브로커에 연결하고 구성한 토픽을 구독합니다.
- Health Auto Export에서 자동화를 열고 기존 데이터 내보내기 아래에서 수동 업로드를 선택합니다.
- 시작과 종료 날짜를 설정한 뒤 내보내기 시작을 선택합니다.
- 수신한 JSON과 날짜를 확인합니다.
페이로드는 JSON 내보내기 형식을 따릅니다. 예:
{
"data": {
"metrics": [
{
"name": "step_count",
"units": "count",
"data": [{"date": "2024-02-06 00:00:00 -0800", "qty": 8500}]
}
]
}
}
문제 해결
- 연결 실패: 호스트, 포트, 네트워크 액세스, 브로커 연결 요구 사항을 확인하세요.
- 인증 실패: 자격 증명과 토픽에 대한 게시 권한을 확인하세요.
- 메시지 없음: 구독자가 같은 브로커와 정확한 토픽을 사용하는지 확인하고 활동 로그를 검토하세요.
- 메시지가 너무 큼: 지표를 줄이고, 범위를 짧게 하거나, 더 거친 시간 그룹화를 선택하세요.
자동화를 열고 활동 로그 보기로 실행을 검토하세요. 경고는 느린 데이터 조회 등 잠재적 문제를 표시하고, 오류는 실패한 단계를 식별합니다. 문제 보고 방법은 도움말 받기를 참조하세요.