Google Health API에서 데이터를 사용하는 것은 기본적으로 클라우드의 Google Health API 데이터 스토어와 자체 앱 또는 백엔드 데이터 스토어 간에 데이터를 동기화하는 사이클입니다. 하지만 이 주기는 다양한 요인에 따라 다른 형태를 취할 수 있습니다.
- Google Health API에 데이터를 쓰고 있나요? 읽기 전용인가요? 아니면 둘 다 해야 하나요?
- 데이터 저장소가 앱 또는 기기에 로컬로 저장되어 있나요? 아니면 자체 클라우드에 있나요?
- 사용자의 앱과 웨어러블 기기 간에 Google Health API 데이터를 동기화해야 하나요? 기기를 얼마나 자주 동기화하나요?
- 어떤 유형의 데이터로 작업하고 있나요? 기본 카운트? 측정 단위 샘플링 비율이 다른 계열이 있나요?
- 앱이 백그라운드에 있는 동안 데이터를 읽을 계획인가요?
- 앱이 사용자 권한을 받기 전에 기록된 과거 데이터를 사용할 계획인가요?
이 모든 것이 어떻게 작동하는지 알아보려면 Google Health API 동기화 수명 주기를 참고하세요. 이 수명 주기에는 표준 (읽기 및 쓰기)과 읽기 전용의 두 가지 버전이 있습니다.
표준 동기화 수명 주기
Google Health API와 통합하면 데이터를 앱 또는 백엔드 데이터 스토어로 복사하게 됩니다. 이 문서에서 사용 편의를 위해 이 데이터 저장소를 개발자 데이터 저장소라고 합니다.
여기서 '복사'는 Google Health API에서 읽기 (개발자 데이터 저장소에 복사) 또는 Google Health API에 쓰기 (Google Health API에 복사)와 같은 개별 활동을 대신할 수 있습니다. 특정 순서로 이러한 작업을 반복하는 것이 동기화 수명 주기입니다.
그림 1은 앞에서 언급한 요소를 고려하지 않고 읽기 및 쓰기 작업을 포함하는 표준 동기화 수명 주기를 보여줍니다.
쓰기
- 쓰기를 위한 새 데이터 준비: 외부 기기 또는 앱에서 데이터를 전송하고 데이터 포인트를 Google Health API 데이터 유형과 호환되는 JSON 표현으로 포맷합니다. 현재 Health API에서는 쓰기를 위한 맞춤 클라이언트 할당 ID가 지원되지 않습니다. 이러한 ID는
POST에 제공될 수 있지만 무시됩니다. - 레코드 삽입/업데이트 - REST 엔드포인트를 사용하여 Google Health API에 데이터 포인트를 제출합니다. 레코드를 만드는 데는
POST를 사용하고 기존 레코드를 삽입하고 업데이트하는 데는PATCH를 사용합니다.PATCH작업에 필요한 ID는 이전POST작업 (이전 주기의 다음 단계)에서 가져온 것입니다. - 반환된 리소스 ID 처리 - 서버 생성 ID를 사용하는 경우 향후 업데이트 (
PATCH) 또는 삭제 (DELETE)를 사용 설정하려면 개발자 데이터 저장소에서 서버에서 반환된 리소스name또는 ID를 추출하고 유지하세요. 두 유형에 관한 자세한 내용은 식별 전략을 참고하세요.
읽기
- 기록 읽기: REST 엔드포인트 (
filter쿼리 매개변수와pageToken페이지로 나누기 또는rollUp,dailyRollUp와 같은 집계 엔드포인트가 있는GET)를 사용하여 Google Health API에서 새 데이터와 기존 데이터의 변경사항을 가져오거나 Webhook 구독 (projects.subscribers)을 사용하여 실시간 알림을 수신합니다. 알림은 새 데이터를 사용할 수 있음을 나타낼 뿐 실제 데이터가 무엇인지는 나타내지 않습니다. - 개발자 데이터 스토어 조정 - 새 데이터와 업데이트된 데이터를 개발자 데이터 스토어에 조정합니다. 연결된 기기는 동기화 중에 중복되는 간격을 생성할 수 있습니다. Google Health API에서 이러한 문제를 해결하는 방법을 알아보려면 간격 타임스탬프 및 연결된 기기 동기화를 참고하세요.
이 주기는 외부 기기 또는 앱의 구체적인 필요에 따라 적절한 간격으로 반복됩니다. 일반적으로 자체 데이터 스토어와 Google Health API 간에 데이터를 동기화할 때 권장되는 순서는 다음과 같습니다.
식별 전략
Google Health API에 데이터를 쓰려는 경우 Google Health API와의 통합을 빌드하기 전에 데이터 포인트 (데이터의 기본 단위)를 만들 때 리소스 식별 전략을 선택해야 합니다.
쓰기를 위한 클라이언트 할당 ID는 현재 Health API에서 지원되지 않습니다.
이러한 ID는 POST에 제공될 수 있지만 무시됩니다. 이 옵션에 관한 세부정보는 정보 제공을 목적으로 여기에 제공됩니다.
- 서버 생성 ID (기본 옵션): 클라이언트가 ID 없이 데이터를 제출하면 Google Health API 백엔드에서 고유한 시스템 식별자를 생성하여 반환합니다.
- 클라이언트 할당 맞춤 ID(AIP-133에 따라 아직 지원되지 않음): 클라이언트 앱이 고유 식별자 (예: UUID 또는 로컬 데이터베이스 기본 키)를 생성하고 생성 시 리소스 경로에 이를 제공합니다.
다음 표에서는 두 식별 전략을 비교하여 통합에 적합한 접근 방식을 선택할 수 있도록 지원합니다.
| 기능 | 서버 생성 ID | 클라이언트 할당 맞춤 ID |
|---|---|---|
| ID 생성 | 서버는 POST 실행 중에 임의의 시스템 ID를 생성합니다. |
클라이언트는 쓰기 전에 안정적인 ID를 로컬로 생성합니다 (UUID v4 / 내부 PK). |
| 리소스 경로 | .../dataPoints/{server_id} (응답으로 반환됨) |
.../dataPoints/{custom_id} |
| 쓰기 후 로컬 단계 | 필수사항. 향후 업데이트/삭제를 지원하려면 반환된 server_id를 로컬 DB에 저장해야 합니다. |
없음. 앱이 이미 ID를 소유하고 있습니다. |
| ID 매핑 테이블 | 필수사항. 클라이언트는 양방향 매핑(local_id ↔ server_id)을 유지해야 합니다. |
필요하지 않습니다. 클라이언트가 자체 기본 키를 직접 사용합니다. |
| 재시도 동작 (약한 네트워크) | 중복 위험 시간이 초과된 POST를 다시 시도하면 새 서버 ID가 있는 중복 레코드가 생성됩니다. |
안전하고 멱등적입니다. 동일한 custom_id로 POST를 다시 시도하면 중복 생성이 방지됩니다 (409
ALREADY_EXISTS 반환). |
| 오프라인 동기화 지원 | 제한됨 공식 리소스 ID를 참조하기 전에 서버 응답을 기다려야 합니다. | Full 안정적인 ID를 사용하여 오프라인에서 항목을 생성하고 변경한 다음 다시 연결되면 원활하게 동기화할 수 있습니다. |
| 형식 제약 조건 | 서버에서 완전히 처리합니다. | ^[a-z0-9-]{4,63}$ (소문자 영숫자 및 하이픈 4~63개)을 따라야 합니다. |
| 선택 기준 |
다음과 같은 경우 서버 생성 ID를 선택하세요.
|
다음과 같은 경우 맞춤 ID를 선택하세요.
|
읽기 전용 동기화 수명 주기
Google Health API에서만 읽으려는 앱은 데이터를 개발자 데이터 스토어에 복사하고 수명 주기의 조정 부분을 처리해야 합니다.
읽기 섹션에서 다룬 작업이 여기에도 적용됩니다.
그림 2는 읽기 전용 수명 주기를 보여줍니다.
인터벌 타임스탬프 및 연결된 기기 동기화
인터벌 데이터는 걸음 수, 심박수, 운동 세션 등 일정 기간 동안 수집된 측정값을 나타냅니다. 반면 특정 시점 측정에는 음식 기록이나 체중계 측정과 같은 수동 입력이 포함됩니다. 인터벌 데이터는 일반적으로 스마트워치, 피트니스 추적기와 같은 연결된 기기를 동기화하여 생성됩니다.
간격 타임스탬프 (startTime 및 endTime)는 간격 데이터를 사용할 때 고유한 동작을 도입합니다. 이 섹션에서는 중복 간격이 발생하는 이유를 설명하고 list 및 reconcile 엔드포인트를 비교합니다.
연결된 기기의 중복 간격
Fitbit 트래커 및 Google Pixel Watch와 같은 연결된 기기는 착용하는 동안 고빈도 생체 인식 데이터를 지속적으로 수집합니다. 기기에서 데이터 포인트를 Google Health에 동기화한 후에는 기존 레코드가 소급하여 변경되지 않습니다. 저장된 간격 타임스탬프는 변경되지 않습니다.
하지만 후속 동기화 주기 전에 온디바이스 알고리즘은 원시 센서 원격 분석을 다시 해석하는 경우가 많습니다. 기기는 이전 시간 동안 수집된 판독값을 다시 버킷팅합니다. 기기가 다시 동기화되면 새 데이터 포인트가 업로드됩니다. 시작 및 종료 경계가 이전에 저장된 간격과 겹칠 수 있습니다.
예를 들어 활동 데이터가 연속된 두 배치로 동기화되는 스마트워치를 착용한 사용자를 생각해 보겠습니다.
- 첫 번째 동기화 중에 기기는
10:00:00Z~10:14:59Z을 포함하는 데이터 포인트를 업로드합니다. - 온디바이스 재계산 후 두 번째 동기화에서는
10:14:00Z~10:28:59Z를 포함하는 다른 데이터 포인트를 업로드합니다.
두 기록은 Google Health 백엔드에 독립적으로 저장됩니다. 따라서 두 데이터 포인트 모두 10:14:00Z부터 10:14:59Z까지의 간격을 포함합니다.
이렇게 하면 원시 레코드를 쿼리할 때 59초의 중복이 발생합니다.
목록 비교 및 엔드포인트 조정
list 또는 reconcile 엔드포인트를 사용하여 이러한 중복 간격을 처리할 수 있습니다. 애플리케이션 요구사항에 맞는 엔드포인트를 선택합니다.
| 기능 | 엔드포인트 list개 |
엔드포인트 reconcile개 |
|---|---|---|
| HTTP 메서드 | GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints:reconcile |
| 중복 동작 | 중복 제거 없이 저장된 모든 레코드를 업로드된 것으로 반환합니다. 간격이 겹치면 두 레코드가 모두 반환됩니다. | 기기 및 동기화 세션 간의 충돌을 해결하고 중복된 레코드를 하나의 연속 스트림으로 중복 제거합니다. |
| 장점 | 각 기기와 동기화 일괄 처리에서 업로드한 모든 레코드의 완전하고 수정되지 않은 감사 추적을 제공합니다. | 중복되는 간격과 멀티 디바이스 간 충돌을 자동으로 처리하여 타임라인 렌더링과 기간 계산을 간소화합니다. |
| 단점 | 애플리케이션은 중복되는 간격, 멀티 디바이스 충돌, 손목에서 벗어난 기간을 감지하고 해결해야 합니다. | 하위 중복 레코드는 응답에서 생략되므로 개별 기기 동기화 일괄 처리를 격리된 상태로 감사할 수 없습니다. |
reconcile 엔드포인트는 사용자 인터페이스를 그리고, 활동 타임라인을 렌더링하고, 중복되지 않는 총 지속 시간을 계산하도록 설계되었습니다. 재분류된 동기화 세션에서 충돌하는 간격을 해결합니다. 또한 시계와 휴대전화 등 여러 기기에서 동시에 기록된 활동을 조정합니다.
조정은 인공 시간 합집합을 합성하는 대신 신뢰할 수 있는 레코드를 선택하여 충돌하는 세션을 해결합니다. 예를 들어 11:00:00Z~11:30:00Z과 11:20:00Z~11:50:00Z을 11:00:00Z~11:50:00Z으로 병합하지 않습니다. 조정된 응답은 원래 기록된 간격과 함께 낙찰된 데이터 포인트를 반환합니다. 이렇게 하면 해당 세션의 측정된 원격 분석과 측정항목의 무결성이 유지됩니다.
그림 3은 reconcile 엔드포인트가 중복 세션을 처리하는 방법을 보여줍니다.
인공 시간 합집합을 만드는 대신 공신력 있는 레코드를 선택합니다.
Endpoints 가이드에서는 완전한 요청 및 응답 예시를 제공합니다. 원시 list 레코드를 reconcile 출력과 비교하려면 조정된 구간 데이터 보기 가져오기를 참고하세요.
list 엔드포인트는 기기 진단 및 데이터 감사를 위해 설계되었습니다. 워크플로에서 각 기기에서 업로드한 대로 수정되지 않은 레코드를 검사해야 하는 경우에 사용합니다. list로 쿼리할 때 클라이언트 로직은 원시 데이터의 간격 중복을 처리해야 합니다.
타임스탬프 변경 가능성 및 소유자 업데이트
연결된 기기는 일반 동기화 주기 중에 저장된 타임스탬프를 소급하여 수정하지 않습니다. 하지만 인터벌 타임스탬프 (startTime 및 endTime)는 모든 데이터 소스에서 보편적으로 불변하지 않습니다. 레코드의 원본 생성자 또는 소유자만 필드를 수정할 수 있습니다. 다른 애플리케이션은 자신이 만들지 않은 데이터 포인트를 수정할 수 없습니다.
소유자 애플리케이션은 patch 엔드포인트를 사용하여 기존 레코드를 업데이트할 수 있습니다. 여기에는 시작 또는 종료 타임스탬프 수정이 포함됩니다.
PATCH로 타임스탬프를 업데이트하는 예는 Endpoints 가이드의 기존 데이터의 업데이트 간격 타임스탬프 업데이트를 참고하세요.
마찬가지로 헬스 커넥트나 파트너 앱과 같은 외부 플랫폼에서 동기화된 데이터 포인트는 원래 소스의 업데이트를 상속합니다. 원래 애플리케이션에서 기존 레코드를 수정하면 이러한 업데이트가 Google Health로 전파됩니다.