중요: 기존 Fitbit Web API 지원이 2026년 9월 30일에 종료됩니다. 이 날짜 이후에도 API는 계속 작동하지만 Google에서 더 이상 버그를 수정하거나 API 지원을 제공하지 않습니다. 2026년 10월 30일에 Fitbit Web API가 사용 중지되며 더 이상 작동하지 않거나 Fitbit 사용자와 데이터를 동기화하지 않습니다. 이 날짜 이후에도 사용자 데이터를 계속 액세스하려면 Google Health API로 이전하세요. 현재는 신규 프로젝트의 온보딩을 진행하고 있지 않지만, 더 많은 개발자가 액세스할 수 있도록 적극적으로 노력하고 있으며, 액세스 가능 범위가 확대되면 이 페이지를 통해 업데이트를 공유할 예정입니다. 전체 일정 및 단계는 Fitbit Web API 이전 가이드를 참고하세요.

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

Google Cloud 및 OAuth 설정

Google Health API에 대한 액세스는 Google Cloud를 통해 제공됩니다. API를 사용 설정하고 Google 계정을 승인하려면 Google Cloud 프로젝트가 필요합니다.

기존 Fitbit API 개발자든 Google Health API를 처음 사용하는 개발자든 API를 호출하려면 이 단계를 완료해야 합니다.

프로젝트 및 OAuth 클라이언트 만들기

API 사용 설정 및 OAuth 2.0 클라이언트 ID 가져오기 버튼을 사용하여 Google Health API를 사용 설정하고 OAuth 2.0 클라이언트 ID를 가져옵니다.

Google Health API에 사용할 기존 Google Cloud 프로젝트가 있는 경우 먼저 해당 프로젝트의 관리자 계정에 로그인해야 합니다. 그런 다음 버튼을 클릭한 후 사용 가능한 프로젝트 목록에서 기존 프로젝트를 선택합니다. 그렇지 않으면 새 프로젝트를 만듭니다.
'어디에서 전화하시나요?'라는 메시지가 표시되면 웹 서버를 선택합니다.
승인된 리디렉션 URI 값으로 https://www.google.com을 입력합니다. OAuth 2.0을 사용하여 승인 코드를 얻으려면 리디렉션 URI가 필요합니다.
설정이 완료되면 OAuth 2.0 클라이언트 ID 및 클라이언트 보안 비밀번호 값을 복사하고 사용자 인증 정보 JSON을 로컬 머신에 다운로드합니다.

Google Cloud 프로젝트를 수동으로 설정하거나 설정을 확인하고 사용자 인증 정보를 다시 가져오려면 다음 단계를 따르세요.

API 사용 설정 페이지에서 Google Health API를 사용 설정합니다.
사용자 인증 정보 페이지에서 OAuth 2.0 클라이언트 ID를 가져옵니다.

Google 콘솔을 사용하여 OAuth 2.0을 설정하는 방법에 관한 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스를 참고하세요.

스테이징 및 프로덕션에 별도의 프로젝트 사용

Google Health API는 별도의 샌드박스 또는 스테이징 환경을 제공하지 않습니다. 모든 환경에서 프로덕션 Google Health API를 호출하므로 Google Cloud 프로젝트 수준에서 환경 분리를 관리합니다.

앱의 환경을 설정할 때는 다음 권장사항을 따르세요.

개발, 스테이징, 프로덕션 환경용으로 별도의 Google Cloud 프로젝트를 만듭니다. 각 프로젝트는 자체 OAuth 2.0 클라이언트, 동의 화면, 웹훅 구독자를 관리합니다.
프로덕션 Google Cloud 프로젝트 또는 해당 OAuth 2.0 클라이언트를 테스트에 사용하지 마세요. 해당 프로젝트의 변경사항이 프로덕션 앱에 직접 영향을 미치기 때문입니다.
먼저 비프로덕션 프로젝트에서 개발하고 테스트한 후 준비가 되면 변경사항을 프로덕션 프로젝트에 적용합니다.
Google Cloud 콘솔에서 태그를 사용하여 환경별로 프로젝트를 시각적으로 구분합니다. 자세한 내용은 태그로 프로젝트 환경 지정을 참고하세요.

테스트 사용자 추가

기본적으로 새로 생성된 OAuth 클라이언트는 테스트 및 프로덕션 목적으로 모두 100명의 사용자 한도가 있는 인증되지 않은 상태입니다. 이 기간 동안 승인을 사용 설정하려면 프로젝트 구성의 테스트 사용자 목록에 각 사용자의 이메일 주소를 수동으로 추가해야 합니다.

잠재고객 페이지에서 테스트 사용자 목록을 업데이트합니다.

이 페이지에서 '게시 상태'가 테스트로 설정되고 '사용자 유형'이 외부로 설정된 것을 확인할 수 있습니다.
'테스트 사용자' 섹션에서 + 사용자 추가를 클릭합니다. 앱이 건강 데이터에 액세스할 수 있는 권한을 부여받을 수 있는 테스트 사용자의 이메일 주소를 입력합니다.
저장을 클릭합니다.

Google Health API를 사용하는 사용자가 100명을 초과하는 경우 서드 파티 보안 검토를 완료해야 합니다. 자세한 내용은 OAuth 앱 인증 고객센터를 참고하세요.

범위 추가

데이터 액세스 페이지에서 클라이언트가 호출할 수 있는 범위를 지정해야 합니다.

이 페이지에서 범위 추가 또는 삭제를 클릭합니다.
API 열에서 'Google Health API'를 검색합니다. 애플리케이션에 필요한 범위를 선택합니다.
필요한 모든 범위를 선택한 후 업데이트를 클릭하여 데이터 액세스 페이지로 돌아갑니다.
저장을 클릭합니다.

범위를 선택하기 전에 범위 구현을 검토하세요.

클라이언트 ID 설정을 완료했으며 이제 Google Health API를 호출할 수 있습니다.

범위 업데이트

인증 요청에서 프롬프트 매개변수를 동의로 설정하여 사용자에게 앱을 다시 승인하라는 메시지를 표시할 수 있습니다. prompt=consent가 포함된 경우 모든 범위가 이전에 Google API 프로젝트에 부여되었더라도 앱에서 액세스 범위 승인을 요청할 때마다 동의 화면이 표시됩니다.

prompt=consent 매개변수를 사용하여 범위를 추가하거나 변경하려면 다음 단계를 따르세요.

애플리케이션에 필요한 범위의 전체 목록을 식별합니다. 여기에는 기존 범위와 추가해야 하는 새 범위가 모두 포함되어야 합니다.
공백으로 구분된 범위 값의 업데이트된 목록을 포함하도록 승인 URL의 범위 매개변수를 수정합니다.
인증 URI 매개변수에 prompt=consent를 추가합니다. 이렇게 하면 승인 서버가 클라이언트에 정보를 반환하기 전에 사용자에게 동의를 요청합니다.

다음 예시에서는 prompt=consent가 추가된 여러 범위를 요청하는 Google의 OAuth 2.0 승인 엔드포인트에 대한 HTTPS GET 요청을 보여줍니다.
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent
```
사용자가 업데이트된 링크를 따라가면 요청된 모든 범위가 나열된 동의 페이지가 표시됩니다. 사용자가 '계속' 또는 '허용'을 클릭하면 전체 범위 집합을 포함하는 토큰으로 교환할 수 있는 새 승인 코드가 전송됩니다.

새 갱신 토큰을 획득해야 하거나 요청된 범위가 변경된 경우와 같이 필요한 경우에만 prompt=consent를 포함하세요.

OAuth2 클라이언트 라이브러리

인기 프레임워크와 통합하는 데 사용되는 사용 가능한 OAuth2 클라이언트 라이브러리 목록은 OAuth 2.0을 사용하여 Google API에 액세스하기에서 확인할 수 있습니다.

모바일 또는 데스크톱 앱에서 Google OAuth를 구현할 때는 항상 시스템 브라우저 (예: Android의 Chrome 맞춤 탭 또는 iOS의 ASWebAuthenticationSession)를 사용하고, 패스키를 차단하고 Google OAuth 흐름을 중단하는 내장 WebView는 사용하지 마세요. Google 계정으로 로그인 권장사항을 검토하여 안내를 확인하세요.

OAuth 동의 전에 Google Health 연결

사용자가 앱에서 Google OAuth 2.0 동의 흐름을 진행하기 전에 Google Health 모바일 앱에 로그인하여 Google Health를 Google 계정에 연결해야 합니다. Google OAuth 2.0은 유효한 Google 계정을 인증하며 동의 화면에서 계정에 활성 Google Health 프로필이 있는지 확인할 수 없습니다.

앱에서 OAuth 동의 흐름을 시작하기 전에 Google 헬스 모바일 앱에서 다음 단계를 완료하도록 사용자에게 안내합니다.

Google Play 스토어 또는 Apple App Store에서 Google Health 모바일 앱을 다운로드하여 엽니다.
Google 계정으로 로그인을 탭하고 앱에 연결할 Google 계정을 선택합니다.
인앱 메시지에 따라 새 Google Health 프로필을 만들거나 Fitbit 계정 이전 단계에 따라 기존 Fitbit 계정을 Google 계정으로 이동합니다.

인증 코드를 OAuth 토큰으로 교환한 후 users.getIdentity 엔드포인트 (GET https://health.googleapis.com/v4/users/me/identity)를 호출하여 사용자의 Google 계정이 Google Health에 연결되어 있는지 확인한 후 앱에서 계정을 연결된 것으로 표시합니다. 연결되지 않은 계정 (400 ACCOUNT_NOT_LINKED) 처리에 관한 자세한 내용은 연결되지 않은 Google 계정 처리를 참고하세요.

갱신 토큰

사용자 재인증을 지속적으로 요구하지 않고 Google API에 장기적으로 액세스하려면 애플리케이션에서 갱신 토큰을 사용해야 합니다. 필요한 특정 HTTP 요청 및 매개변수를 비롯한 포괄적인 구현 세부정보는 Google ID 플랫폼 문서를 참고하세요.

갱신 토큰을 액세스 토큰으로 교환하려면 Google OAuth 2.0 토큰 엔드포인트에 HTTPS POST 호출을 실행합니다. 다음 스니펫은 요청 및 응답의 예를 보여줍니다.

요청

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

응답

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

토큰을 새로고침해야 하는 경우

액세스 토큰이 만료되었거나 만료가 임박한 경우 사용자의 활성 세션이 자연스럽게 진행되는 과정에서 필요에 따라 토큰을 새로고침합니다. 일괄적으로 토큰을 새로고침하지 마세요 (예: 예약된 cron 작업 또는 서비스를 사용하여 고정된 시간에 모든 사용자의 토큰을 새로고침).

다음과 같은 이유로 토큰을 일괄적으로 새로고침하는 것은 권장되지 않습니다.

일괄 새로고침은 토큰 업데이트를 활성 사용자 동기화 패턴과 정렬하는 것을 방지합니다. 기기 가져오기 호출을 사용하여 사용자의 마지막 동기화 시간을 확인할 수 있지만, 이 경우 사용자가 승인하지 않아도 되는 추가 OAuth 범위가 필요합니다.
일괄 처리로 새로고침할 필요가 없는 토큰이 업데이트되어 시스템과 Google 서버 모두에 중복 처리 오버헤드가 발생합니다.
일괄 새로고침 중에 네트워크 문제나 서버 다운이 발생하면 영향을 받는 모든 사용자 토큰이 한 번에 영향을 받습니다. 사용자 동기화가 자연스럽게 진행되는 동안 토큰을 개별적으로 새로고침하면 일시적인 오류의 영향을 단일 사용자로 격리할 수 있습니다.
일괄 작업에서는 문제를 진단하기가 더 어렵습니다. 일괄 요청은 빈도가 낮고 한 번에 많은 로그 항목을 생성하므로 인시던트의 시작을 정확히 파악하기가 더 어렵습니다.
일괄 실행 중에 토큰 요청의 동시성이 급증하면 비율 제한에 도달하거나 간헐적인 인증 오류가 발생할 가능성이 높아집니다.

테스트 중 토큰 동작

Google Cloud 프로젝트의 게시 상태에 따라 새로고침 토큰이 어떻게 작동하는지 알아두세요.

테스트 모드: OAuth 동의 화면이 '테스트' 게시 상태로 구성된 경우 발급된 갱신 토큰은 시간 기반이며 7일 후에 만료됩니다. 이 기간 동안 만료일까지 유효하며 새 액세스 토큰을 획득하는 데 사용할 수 있는 단일 갱신 토큰이 제공됩니다.
게시됨 모드: 앱이 '프로덕션' 상태로 이동되면 일반적으로 갱신 토큰은 취소되거나 장기간 (일반적으로 6개월) 사용되지 않는 한 만료되지 않습니다.

원활한 사용자 환경을 위해 프로덕션 환경으로 이동하기 전에 애플리케이션을 게시하여 7일 토큰 만료를 방지하세요.

샘플 데이터 생성

Google에서는 미리 채워진 샘플 또는 모의 건강 데이터를 제공하지 않습니다. 통합을 테스트하려면 자체 테스트 데이터를 생성해야 합니다. 다음 방법 중 하나를 사용하여 테스트 사용자의 샘플 데이터를 생성합니다.

트래커 착용: Fitbit 트래커, Pixel Watch 또는 Google Health 앱과 호환되는 기타 스마트워치를 착용하고 걸어 다니며 걸음 수, 심박수, 운동 데이터를 생성합니다.
모바일 추적 사용 설정: Google Health 앱에서 MobileTrack을 사용 설정하고 휴대기기를 들고 걸어 다닙니다.
수동으로 데이터 기록: Google Health 앱을 통해 수면, 체중, 물 또는 음식 섭취량과 같은 건강 측정항목을 수동으로 입력합니다.
API를 사용하여 데이터 쓰기: POST 또는 PATCH와 같은 쓰기 요청을 REST API 엔드포인트로 직접 보내 프로그래매틱 방식으로 데이터를 채웁니다. 데이터 포인트 생성 및 업데이트에 대한 자세한 내용은 REST 참조 문서를 참고하세요.

계정 간 보안 (RISC API)

저장된 토큰을 정리하고 UI 연결 상태를 업데이트하기 위해 연결 해제된 계정이나 취소된 토큰과 같은 이벤트 토큰 또는 계정 연결의 변경사항에 대한 알림을 받으려면 위험 및 인시던트 공유 및 조정 (RISC)을 사용 설정하세요. RISC API 사용 설정은 선택사항입니다.

Google Cloud 프로젝트에 RISC API를 사용 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 RISC API 페이지를 엽니다. Google Health API에 사용할 프로젝트가 선택되어 있는지 확인합니다.
RISC 약관을 읽고 요구사항을 이해했는지 확인합니다.
약관에 동의하면 사용 설정을 클릭합니다.

API를 사용 설정한 후에는 Google에서 전송한 이벤트 토큰을 수신하고 검증할 HTTPS 엔드포인트를 만들어 등록해야 합니다.

계정 간 보안 및 RISC에 대한 자세한 내용은 계정 간 보안으로 사용자 계정 보호하기를 참고하세요.

Google Cloud 및 OAuth 설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.