중요: 2026년 9월 30일에 기존 Fitbit Web API 지원이 종료되었습니다. 2026년 11월 2일에 기존 Fitbit Web API 및 Fitbit OAuth 엔드포인트가 사용 중지되며 더 이상 작동하지 않거나 Fitbit 사용자와 데이터를 동기화하지 않습니다. 이 날짜 이후에도 사용자의 데이터에 계속 액세스하려면 Google Health API로 이전하세요. 이전 가이드는 Fitbit Web API 이전 가이드를 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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에 쓰기(Google Health API에 복사)와 같은 개별 활동을 대체할 수 있습니다. 이러한 작업을 특정 순서로 반복적으로 수행하는 것이 동기화 수명 주기입니다.

그림 1은 이전에 언급된 요소를 고려하지 않고 읽기 및 쓰기 작업을 포함하는 표준 동기화 수명 주기를 보여줍니다.

쓰기

쓰기용 새 데이터 준비 — 외부 기기 또는 앱에서 데이터를 전송하고 데이터 포인트를 Google Health API 데이터 유형과 호환되는 JSON 표현으로 형식화합니다. 현재 Health API에서는 쓰기에 대한 맞춤 클라이언트 할당 ID가 지원되지 않습니다. 이러한 ID는 POST에 제공될 수 있지만 무시됩니다.
레코드 upsert — REST 엔드포인트를 사용하여 Google Health API에 데이터 포인트를 제출합니다. POST를 사용하여 레코드를 만들고 PATCH를 사용하여 기존 레코드를 삽입하고 업데이트합니다. PATCH 작업에 필요한 ID는 이전 POST 작업(이전 주기의 다음 단계)에서 가져옵니다.
반환된 리소스 ID 처리 — 서버 생성 ID를 사용하는 경우 향후 업데이트(PATCH) 또는 삭제(DELETE)를 사용 설정하기 위해 개발자 데이터 스토어에서 서버 반환 리소스 name 또는 ID를 추출하고 저장합니다. 두 유형에 대한 자세한 내용은 식별 전략을 참조하세요.

읽기

기록 읽기 — REST 엔드포인트(filter 쿼리 매개변수 및 pageToken 페이지로 나누기가 있는 GET 또는 rollUp 및 dailyRollUp와 같은 집계 엔드포인트)를 사용하여 Google Health API에서 새 데이터 및 기존 데이터의 변경사항을 가져오거나 웹훅 구독(projects.subscribers)을 사용하여 알림을 수신합니다. 알림은 새 데이터를 사용할 수 있다는 것만 나타내며 실제 데이터가 무엇인지는 나타내지 않습니다.
개발자 데이터 스토어 조정 — 새 데이터와 업데이트된 데이터를 개발자 데이터 스토어에 조정합니다. 연결된 기기는 동기화 중에 겹치는 간격을 생성할 수 있습니다. Google Health API에서 이를 해결하는 방법을 알아보려면 간격 타임스탬프 및 연결된 기기 동기화를 참고하세요.

이 주기는 외부 기기 또는 앱의 특정 요구사항에 따라 적절한 간격으로 반복됩니다. 이는 일반적으로 자체 데이터 스토어와 Google Health API 간에 데이터를 동기화하는 데 권장되는 순서입니다.

식별 전략

Google Health API에 데이터를 쓰려면 Google Health API와의 통합을 빌드하기 전에 데이터 포인트(데이터의 기본 단위)를 만들 때 리소스 식별 전략을 선택해야 합니다.

현재 Health API에서는 쓰기에 클라이언트 할당 ID가 지원되지 않습니다. 이러한 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를 참조하기 전에 서버 응답을 기다려야 합니다.	전체 안정적인 ID를 사용하여 오프라인에서 항목을 만들고 변경한 다음 다시 연결되면 원활하게 동기화할 수 있습니다.
형식 제약 조건	서버에서 전적으로 처리합니다.	`^[a-z0-9-]{4,63}$`(4~63자(영문 기준)의 소문자 영숫자 및 하이픈)을 따라야 합니다.
선택 기준	다음과 같은 경우 서버 생성 ID를 선택합니다. 앱이 쓰기 전용/추가 전용입니다(예: 나중에 업데이트되거나 삭제되지 않는 원격 분석 또는 걸음 수 전송). 앱이 개별 데이터 포인트의 로컬 영구 데이터베이스를 유지하지 않습니다. 문자열 유효성 검사 제약조건(예: `4-63`자)을 관리하지 않고 단순성을 선호합니다.	다음과 같은 경우 커스텀 ID를 선택하세요. 기기 간에 건강 기록을 읽고 쓰고 업데이트하는 양방향 동기화 앱을 운영합니다. 앱에 로컬 기본 키가 있는 레코드를 저장하는 로컬 데이터베이스(예: Room 또는 SQLite)가 있습니다. 사용자가 오프라인으로 또는 안전한 재시도가 필요한 간헐적인 모바일 연결을 통해 데이터를 기록합니다. 백엔드 데이터베이스와 API 간의 ID 매핑 테이블을 제거하려고 합니다.

읽기 전용 동기화 수명 주기

Google Health API에서 읽기만 하려는 앱은 데이터를 개발자 데이터 스토어에 복사하고 수명 주기의 조정 부분을 처리해야 합니다.

읽기 섹션에서 다룬 것과 동일한 작업이 여기에 적용됩니다.

그림 2는 읽기 전용 수명 주기를 보여줍니다.

인터벌 타임스탬프 및 연결된 기기 동기화

간격 데이터는 걸음 수, 심박수, 운동 세션과 같이 일정 기간 동안 수집된 측정값을 나타냅니다. 반면 특정 시점 측정에는 음식 기록이나 체중계 측정값과 같은 수동 입력이 포함됩니다. 인터벌 데이터는 일반적으로 스마트시계 및 피트니스 트래커와 같은 연결된 기기를 동기화하는 데서 비롯됩니다.

간격 타임스탬프(REST JSON 페이로드의 startTime 및 endTime 또는 필터 표현식 및 gRPC의 start_time 및 end_time)는 간격 데이터를 사용할 때 고유한 동작을 도입합니다. 이 섹션에서는 겹치는 간격이 발생하는 이유를 설명하고 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/dataType/dataPoints`	`GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile`
중복 동작	저장된 모든 레코드를 중복 삭제 없이 업로드된 상태로 반환합니다. 간격이 겹치면 두 레코드가 모두 반환됩니다.	여러 기기와 동기화 세션에서 발생하는 충돌을 해결하고 중복되는 기록을 하나의 연속 스트림으로 중복 삭제합니다.
장점	각 기기 및 동기화 배치에서 업로드한 모든 레코드의 수정되지 않은 전체 감사 추적을 제공합니다.	겹치는 간격과 멀티 디바이스 충돌을 자동으로 처리하여 타임라인 렌더링 및 기간 계산을 간소화합니다.
단점	애플리케이션은 겹치는 간격, 멀티 디바이스 충돌, 손목 미착용 기간을 감지하고 해결해야 합니다.	하위 중복 레코드는 응답에서 생략되므로 개별 기기 동기화 배치를 개별적으로 감사할 수 없습니다.

reconcile 엔드포인트는 사용자 인터페이스를 그리고, 활동 타임라인을 렌더링하고, 겹치지 않는 총 기간을 계산하도록 설계되었습니다. 다시 버케팅된 동기화 세션에서 충돌하는 간격을 해결합니다. 또한 시계와 휴대전화와 같은 여러 기기에서 동시에 기록된 활동을 조정합니다.

조정은 인공 시간 합집합을 합성하는 대신 권한 있는 레코드를 선택하여 충돌하는 세션을 해결합니다. 예를 들어 11:00:00Z~11:30:00Z 및 11:20:00Z~11:50:00Z를 11:00:00Z~11:50:00Z로 병합하지 않습니다. 조정된 응답은 원래 기록된 간격과 함께 선정된 데이터 포인트를 반환합니다. 이렇게 하면 해당 세션의 측정된 원격 분석 및 측정항목의 무결성이 유지됩니다.

그림 3은 reconcile 엔드포인트가 중복 세션을 처리하는 방법을 보여줍니다. 인공 시간 합집합을 만드는 대신 신뢰할 수 있는 레코드를 선택합니다.

겹치는 간격 해결: 엔드포인트 중복 삭제와 인공 시간 합집합 병합 조정 — *그림 3: 충돌하는 세션 조정과 인공 시간 통합 병합 비교*

Endpoints 가이드에서는 전체 요청 및 응답 예시를 제공합니다. 원시 list 레코드를 reconcile 출력과 비교하려면 간격 데이터의 조정된 뷰 가져오기를 참조하세요.

list 엔드포인트는 기기 진단 및 데이터 감사를 위해 설계되었습니다. 워크플로에서 각 기기에서 업로드한 수정되지 않은 레코드를 검사해야 하는 경우에 사용합니다. list로 쿼리할 때 클라이언트 로직은 원시 데이터의 간격 중복을 처리해야 합니다.

타임스탬프 변경 가능성 및 소유자 업데이트

연결된 기기는 정상적인 동기화 주기 동안 저장된 타임스탬프를 소급하여 수정하지 않습니다. 그러나 간격 타임스탬프(REST JSON 페이로드의 startTime 및 endTime 또는 필터 표현식 및 gRPC의 start_time 및 end_time)는 모든 데이터 소스에서 보편적으로 변경할 수 없습니다. 레코드의 원래 작성자 또는 소유자만 필드를 수정할 수 있습니다. 다른 애플리케이션은 자신이 만들지 않은 데이터 포인트를 수정할 수 없습니다.

소유자 애플리케이션은 patch 엔드포인트를 사용하여 기존 레코드를 업데이트할 수 있습니다. 여기에는 시작 또는 종료 타임스탬프 수정이 포함되며, 이를 통해 서버의 UTC(startTime 및 endTime) 및 시민 시간(civilStartTime 및 civilEndTime) 필드가 모두 업데이트됩니다. PATCH로 타임스탬프를 업데이트하는 예시는 엔드포인트 가이드의 기존 데이터의 간격 타임스탬프 업데이트를 참고하세요.

마찬가지로 헬스 커넥트나 파트너 앱과 같은 외부 플랫폼에서 동기화된 데이터 포인트는 원래 소스의 업데이트를 상속합니다. 이후에 헬스 커넥트가 원래 서드 파티 앱에서 동기화된 레코드의 업데이트를 수신하면 이러한 변경사항이 전파되어 기존 레코드를 덮어씁니다.

사용자 프로필 정보