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

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

개요

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

사용 사례:

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

주요 기능:

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

제한 사항

• 건강 데이터 액세스: iPhone이 잠겨 있는 동안 앱은 건강 데이터에 액세스할 수 없습니다. 자동화는 기기가 잠금 해제된 기간에만 실행됩니다. 이는 데이터 신선도에 영향을 줄 수 있습니다. 데이터를 최신 상태로 유지하기 위한 수동 동기화 지침을 참조하세요.

• 백그라운드 처리: iOS는 배터리 수명을 보존하기 위해 백그라운드 처리를 제한합니다. 자동화는 백그라운드 앱 새로고침에 의존하며 다음 경우 즉시 실행되지 않을 수 있습니다:

  • 앱의 백그라운드 앱 새로고침이 비활성화된 경우
  • 기기가 저전력 모드에 있는 경우
  • 기기가 장기간 비활성 상태였던 경우
  • 시스템 리소스가 제한된 경우
  • 여러 앱이 백그라운드 실행 시간을 경쟁하는 경우

사전 요구 사항

• 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

헤더를 추가하려면:

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

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

데이터 유형 설정

데이터 유형

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

• 건강 지표 - 걸음 수, 심박수, 수면 및 기타 건강 측정값
• 운동 - 운동 및 피트니스 활동
• 증상 - 건강 증상 및 상태
• 심전도 - 심전도 판독값
• 심박수 알림 - 높음/낮음 심박수 이벤트
• 마음 상태 - 기분 및 정신 상태 항목(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 형식을 사용하는 경우 일괄 요청을 켜서 단일 페이로드 대신 여러 요청에 걸쳐 데이터를 일괄로 전송합니다.

• 켜기 - 과도하게 큰 페이로드를 방지하기 위해 데이터를 여러 요청에 분산
• 끄기 - 모든 데이터를 단일 요청으로 전송

동기화 빈도

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

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

테스트 및 확인

수동 테스트

1. 자동화 구성 화면에서 "수동 내보내기"를 탭
2. 날짜 범위 선택
3. 테스트 요청을 보내려면 "내보내기"를 탭
4. 데이터가 수신되었는지 확인하기 위해 엔드포인트 확인

활동 로그 보기

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

데이터 형식 확인

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

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

문제 해결

일반적인 문제

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

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

팁 및 모범 사례

1. 성능:

   • 세부 정보와 데이터 크기의 균형을 맞추기 위해 적절한 시간 그룹화 사용
   • 필요한 지표만 선택

2. 신뢰성:

   • 엔드포인트의 응답 시간에 따라 적절한 시간 제한 값 설정
   • 활동 로그를 정기적으로 모니터링

3. 데이터 형식:

   • 구조화된 데이터 및 API에 JSON 사용
   • 간단한 데이터 분석 또는 스프레드시트 통합에 CSV 사용
   • 대용량 데이터 세트 또는 별도 처리에 대한 일괄 요청 고려