Apple Health 데이터를 REST API에 동기화

건강 데이터를 REST API 엔드포인트로 전송합니다.

Last updated: June 9, 2026

이 페이지에서

REST API 자동화 가이드

REST API 자동화를 통해 HTTP POST 요청을 수락하는 모든 웹 서비스로 건강 데이터를 자동으로 내보낼 수 있습니다. 맞춤 백엔드, 서드파티 API 또는 웹훅과 통합하는 데 이상적입니다.

개요

REST API 자동화는 HTTP POST 요청을 사용하여 지정된 URL 엔드포인트로 건강 데이터를 전송합니다. 자동화는 인증 및 사용자 정의 메타데이터를 위한 구성 가능한 헤더와 함께 JSON 또는 CSV 형식으로 데이터를 전송할 수 있습니다.

사용 사례:

맞춤 백엔드 서비스와 통합
웹훅으로 데이터 전송
서드파티 API와 동기화
맞춤 대시보드 또는 분석 플랫폼 구축

주요 기능:

JSON 및 CSV 형식 모두 지원
인증을 위한 사용자 정의 HTTP 헤더
구성 가능한 요청 시간 제한
기록 데이터의 수동 내보내기

제한 사항:

건강 데이터 액세스: iPhone이 잠겨 있는 동안에는 앱이 건강 데이터에 액세스할 수 없습니다. 자동화는 기기가 잠금 해제된 기간에만 실행됩니다. 이는 Apple이 부과하는 제한이며 우회할 수 없습니다. 자세한 정보
백그라운드 처리: iOS는 배터리 수명을 위해 백그라운드 처리를 제한합니다. 자동화는 백그라운드 앱 새로 고침에 의존하며 다음 경우 즉시 실행되지 않을 수 있습니다:
- 앱에 대해 백그라운드 앱 새로 고침이 꺼져 있음
- 기기가 저전력 모드임
- 기기가 오랫동안 비활성 상태였음
- 시스템 리소스가 부족함
- 여러 앱이 백그라운드 실행 시간을 경쟁함

성능

iOS는 매우 엄격한 성능 제약이 있는 모바일 기기에서 짧게 실행되는 작업에 최적화되어 있다는 점을 유의하세요. 백그라운드 작업은 일반적으로 30초 이내에 완료되어야 하며 사용할 수 있는 메모리도 제한됩니다. Health Auto Export는 높은 유연성과 맞춤 설정을 제공하므로, 특정 구성이 앱 성능과 결과에 어떤 영향을 미치는지 이해하는 것이 중요합니다.

구성: 많은 양의 데이터를 생성하는 자동화는 시스템이 프로세스를 종료하게 하여 백그라운드에서 자동화가 실행되지 않을 수 있습니다. 다음 구성은 많은 양의 데이터를 생성할 수 있습니다:
- 모든 건강 지표를 내도록 구성된 자동화.
  - 권장: Apple 건강에 저장된 데이터가 있는 건강 지표만, 실제로 사용할 데이터만 선택하세요. 비어 있는 데이터 유형도 성능에 영향을 줍니다. 선택한 건강 지표를 여러 자동화로 나누는 것도 고려하세요. 시스템이 처리하기 쉬워집니다.
- 초 또는 분 단위 시간 그룹화를 사용하거나 데이터 요약이 꺼진 자동화. 이런 세밀한 쿼리는 오래 걸리고 시스템 제한과 충돌할 수 있습니다.
  - 권장: 가능한 한 상세한 데이터가 이상적으로 보일 수 있지만, 각 지표나 데이터 유형에 그 수준의 상세가 필요한지 검토하세요. 설정이 다른 여러 자동화를 고려하세요.
- 사이클링, 달리기, 하이킹 등 실외 운동을 경로 데이터와 함께보낼 때 GPS와 관련 건강 지표 데이터가 큰 페이로드를 만들 수 있습니다.
페이로드 크기: REST API보내기를 사용할 때 특히 큰 페이로드가 서버 오류를 일으킬 수 있습니다. 백엔드가 수백 메가바이트 규모의 페이로드를 처리할 수 있도록 구성되어 있는지 확인하세요.
동기화 빈도: 홈 화면에 자동화 위젯을 추가하면 백그라운드에서 자동화가 더 안정적으로 실행되도록 도울 수 있습니다(자동화용 위젯 설정 참조).

사전 요구 사항

HTTP POST 요청을 수락하는 유효한 URL 엔드포인트
인증 자격 증명(엔드포인트에서 필요한 경우)
엔드포인트에 도달하기 위한 네트워크 연결

구성

메인 탐색에서 자동 내보내기 화면으로 이동한 다음 "새 자동화"를 탭하고 자동화 유형으로 "REST API"를 선택합니다.

자동화 이름

자동화에 대한 설명 이름을 입력합니다(예: "내 백엔드 API", "웹훅 통합").

알림

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

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

URL 구성

건강 데이터를 전송할 전체 URL을 입력합니다. 프로토콜(http:// 또는 https://)을 포함한 전체 URL이어야 합니다.

URL 예:

https://api.example.com/health-data
https://webhook.site/your-unique-id
http://localhost:3000/api/health

참고: URL이 유효하고 기기에서 액세스 가능해야 합니다. 잘못된 URL은 자동화 실행을 방지합니다.

요청 시간 제한

HTTP 요청에 대한 시간 제한 간격을 선택합니다. 이는 요청이 실패한 것으로 간주되기 전에 앱이 응답을 기다리는 시간을 결정합니다.

HTTP 헤더

인증 또는 메타데이터를 위한 사용자 정의 HTTP 헤더를 추가합니다. 일반적인 사용 사례는 다음과 같습니다:

API 키: X-API-Key: your-api-key
인증 토큰: Authorization: Bearer your-token
콘텐츠 유형 재정의: Content-Type: application/json

헤더를 추가하려면:

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

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

데이터 유형 설정

데이터 유형

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

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

건강 지표 구성

건강 지표가 선택된 경우:

건강 지표 선택 - 포함할 특정 지표를 선택합니다. 사용 가능한 모든 지표를 선택하거나 특정 지표를 선택할 수 있습니다.

팁: 필요한 지표만 선택하면 처리 시간을 개선하고 데이터 크기를 줄일 수 있습니다.

선호 소스 - 여러 소스가 동일한 지표를 제공할 때 우선순위를 가질 데이터 소스를 구성합니다.

운동 구성

운동이 선택된 경우:

경로 데이터 포함 - 위치 데이터가 있는 운동의 경로를 포함하려면 켭니다.

운동 지표 포함 - 운동 중 수집된 건강 지표(심박수, 칼로리 등)를 포함하려면 켭니다.

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

분 - 운동 지표를 분별로 그룹화
초 - 운동 지표를 초별로 그룹화

내보내기 설정

내보내기 형식

내보낸 데이터의 형식을 선택합니다:

JSON 형식 - 중첩된 개체가 있는 상세한 데이터 구조를 제공합니다. 구조화된 데이터가 필요한 API, 데이터베이스 및 애플리케이션에 가장 적합합니다. JSON 형식에는 수면 단계 및 AFib 판독값과 같은 복잡한 데이터 유형에 대한 더 자세한 정보가 포함됩니다.
CSV 형식 - 스프레드시트 애플리케이션에 쉽게 가져올 수 있는 테이블 형식 데이터를 제공합니다. 간단한 데이터 분석 또는 엔드포인트가 CSV 데이터를 예상하는 경우에 가장 적합합니다.

참고: Content-Type 헤더는 JSON 내보내기의 경우 application/json으로, CSV 내보내기의 경우 multipart/form-data로 자동 설정됩니다.

내보내기 버전

내보내기 버전을 선택합니다. 버전 관리를 통해 자신의 속도로 내보내기의 업데이트된 버전 간에 전환할 수 있으며 워크플로를 중단하는 변경 사항을 최소화합니다.

버전 1 - 레거시 형식, 이 형식에 의존하는 기존 워크플로가 있는 경우 사용
버전 2 - 향상된 운동 데이터 및 더 자세한 메타데이터 옵션이 있는 현재 형식

날짜 범위

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

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

데이터 요약

건강 지표 데이터 유형과 함께 JSON 형식을 사용하는 경우 데이터 요약을 켜거나 끕니다.

켜기 - 집계된 데이터 요약 제공
끄기 - 가능한 경우 비집계 데이터를 제공하여 개별 데이터 포인트 표시

참고: 이 설정은 건강 지표가 있는 JSON 형식에만 적용됩니다. CSV 형식을 사용하거나 여러 지표가 선택된 경우 데이터는 항상 집계됩니다.

시간 그룹화

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

참고: CSV 형식은 항상 데이터를 집계합니다. 분 및 초 수준 집계는 처리 시간과 데이터 크기를 크게 증가시킬 수 있습니다.

일괄 요청 및 대용량 페이로드

JSON 형식을 사용할 때 일괄 요청을 켜면 하나의 큰 페이로드 대신 여러 HTTP 요청으로 데이터를 보냅니다.

켜짐 — 데이터를 여러 요청으로 나눕니다. 엔드포인트에 페이로드 크기 제한, 큰 본문의 시간 초과 또는 점진적 처리가 있을 때 사용하세요.
꺼짐 — 모든 데이터를 단일 요청으로 보냅니다. 작은보내기와 간단한 웹훅에 적합합니다.

일괄 처리를 켜는 경우:

많은 건강 지표 선택, 긴 날짜 범위 또는 세밀한 시간 그룹화(분/초)
데이터 요약이 꺼져 있고 분리된 건강 지표를보내는 경우
서버가 큰 POST 본문에서 오류 또는 시간 초과를 반환하는 경우

참고:

일괄 요청은 REST API + JSON에만 적용됩니다(CSV 아님).
일괄 처리는 요청당 페이로드를 줄이지만 기기에서 데이터를 가져올 필요는 없애지 않습니다. 느린 HealthKit 쿼리는 활동 로그에 경고로 나타날 수 있습니다. 활동 로그의 느린 쿼리를 참고하세요.

동기화 빈도

자동화가 데이터를 업로드할 빈도를 구성합니다:

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

테스트 및 확인

데이터 형식 확인

앱은 각 요청에 자동으로 다음 헤더를 포함합니다:

Content-Type - 내보내기 형식에 따라 설정
automation-name - 자동화 이름
automation-id - 자동화의 고유 식별자
automation-aggregation - 선택한 시간 그룹화
automation-period - 선택한 날짜 범위
session-id - 각 요청의 고유 식별자

문제 해결

일반적인 문제

엔드포인트에서 데이터를 받지 못함

엔드포인트 URL이 올바른지 확인
엔드포인트가 POST 요청을 수락하는지 확인
인증 헤더 검토
들어오는 요청에 대한 엔드포인트 로그 확인
네트워크 연결 확인

팁 및 모범 사례

자동 동기화:
- 기기를 충전하고 iPhone 미러링 사용
  - 충전 중에는 iOS가 성능 제한을 덜 두므로 데이터를 더 자주 동기화할 수 있습니다
  - iPhone 미러링을 사용하면 기기가 잠금 해제된 것처럼 동작합니다. Health Auto Export가 건강 데이터에 접근해 자동화를 실행할 수 있습니다
성능:
- 세부 정보와 데이터 크기의 균형을 맞추기 위해 적절한 시간 그룹화 사용
- 필요한 지표만 선택
신뢰성:
- 엔드포인트의 응답 시간에 따라 적절한 시간 제한 값 설정
- 활동 로그를 정기적으로 모니터링
데이터 형식:
- 구조화된 데이터 및 API에 JSON 사용
- 간단한 데이터 분석 또는 스프레드시트 통합에 CSV 사용
- 대용량 데이터 세트 또는 별도 처리에 대한 일괄 요청 고려

활동 로그 보기

자동화 구성 화면에서 활동 로그 보기을(를) 탭합니다.
실행을(를) 검토합니다(최신순 그룹). 각 실행을 펼쳐 이벤트를 확인합니다.
경고(예: 느린 건강 데이터 쿼리)과 오류(HTTP 실패, 시간 초과 또는 HealthKit 읽기 실패)을(를) 구분합니다—자동화 개요 — 활동 로그 참고.
성공한 REST 업로드는 실행에 형식, 데이터 유형, 보내기 기간, 날짜 범위가 포함된 요약을 자주 표시합니다.
공유 (도구 모음) exports the full 앱 이벤트 로그 diagnostic ZIP for support (same as 설정 → 고급).
지우기 은 이 자동화의 활동 기록만 제거합니다.