Google Health API は、ゼロから構築された包括的なソリューションです。デベロッパーは、同意を得たユーザーの健康に関する幅広いデータとさまざまなデータタイプに、堅牢な方法でアクセスできます。Google Health API は、アプリの登録、Google OAuth 2.0、新しいデータ型、新しいエンドポイント スキーマ、新しいレスポンス形式に新しいコンソールを使用します。
このガイドは、デベロッパーが既存の Fitbit Web API アプリを新しい Google Health API に移行する際に役立つように作成されています。ユーザーを維持しながらシームレスに移行するための推奨事項が示されます。
移行が必要な理由
これは単なるアップデートではなく、アプリのセキュリティを確保し、健康テクノロジーの将来の進歩に備えるための戦略的な取り組みです。Google Health API を使用するメリットには、次のようなものがあります。
- 包括的なデータへのアクセス: ユーザーが同意した健康に関するデータやさまざまなデータタイプに、堅牢なアクセスを実現します。
- セキュリティの強化: Google のセキュリティのベスト プラクティスに準拠し、Google のセキュリティ、プライバシー、ID の標準に沿っています。
- 一貫性: データ形式、タイムゾーン、測定単位、エラー処理における以前の不整合を解消し、より直感的なデベロッパー エクスペリエンスを実現します。
- スケーラビリティと将来への対応: 将来の需要に合わせてスケーリングできるように設計されており、gRPC などの最新のプロトコルをサポートしています。
Fitbit Web API から Google Health API への移行には、技術的な変更だけでなく、新しい OAuth ライブラリに切り替えるため、既存のアクセス トークンと更新トークンを転送できません。ユーザーは、更新された統合に再度同意する必要があります。
両方のログイン方式をサポートする
Fitbit Web API と Google Health API では、ユーザー ログインの処理に異なるシステムが使用されるため、Fitbit Web API がまだ有効な間は、アプリは一時的にユーザーベース全体で両方の認証方法をサポートする必要があります。
アプリがデータを直接リクエストするのではなく、特定のユーザーに対して Fitbit Web API と Google Health API のどちらと通信するかを決定するレイヤを実装します。これにより、アプリの他の部分で詳細を気にする必要がなくなります。
ユーザー データベースを更新して、使用しているログイン システムを識別するフラグ(oauth_type など)を追加します。
- 新規ユーザーの場合: 新しい Google Health API(
oauth_type: google)を自動的に設定します。 - 既存ユーザーの場合: 同意(
oauth_type: fitbit)を更新するまで、Fitbit Web API を使用し続けます。
| ユーザー シナリオ | oauth_type 州 |
アクティブな API ストリーム | 必要な操作 |
|---|---|---|---|
| 新規ユーザーのオンボーディング | google |
Google Health API のみ | システム ブラウザで Google OAuth を起動し、users.getIdentity を使用して ID をマッピングします。 |
| 既存の Fitbit ユーザー(まだ移行していない) | fitbit |
Fitbit Web API のみ | Fitbit Web API との同期を継続し、アップグレードを促す閉じることが可能なアプリ内メッセージを表示します。 |
| 既存の Fitbit ユーザーが移行を完了する | fitbit → google |
Google Health API に切り替える | 付与されたスコープを確認し、users.getIdentity(legacyUserId → healthUserId)を呼び出し、oauth_type を google に切り替えて、以前の Fitbit トークンを直ちに取り消します。 |
ユーザー エクスペリエンスを損なわないようにするため、すべてのユーザーにログアウトと再ログインを強制しないことをおすすめします。この場合は次のように対応してください。
- Fitbit Web API に接続したままのユーザーがアプリを操作したときに、接続を更新するよう促すわかりやすい通知を表示します。
- ユーザーが更新アクションを承認したら、すぐに Google Health のログインフローをトリガーします。
- Google ログインが成功したら、新しい Google 認証情報をユーザーのプロフィールに保存し、
oauth_typeフラグをfitbitからgoogleに切り替えます。また、以前の Fitbit トークンを取り消すことで、以前の同期をプログラムで直ちに無効にし、データの取り込みの重複や二重リンクを防ぎます。
データの連続性を確保する
以前の Fitbit Web API から Google Health API に統合を移行する場合、デベロッパー アプリケーションはユーザー識別構造の変更を考慮する必要があります。
以前の Fitbit Web API では、6 文字の英数字文字列(A1B2C3 など)を使用してアカウントを識別しますが、Google Health API では、最大 63 桁の数字と文字の文字列としてフォーマットされた healthUserId を使用します。
ユーザー コンテキストを失うことなくこのギャップを埋めるために、デベロッパーは getIdentity エンドポイントにクエリを実行して Fitbit と Health のユーザー ID を取得できます。このエンドポイントは、legacyUserId と新しい healthUserId の両方を含むペイロードを返します。これにより、アプリケーションは既存のレコードと新しいアカウント システム間のマッピングを動的に作成できます。
リンクされていない Google アカウントに対応する
アプリが Google Health API を介してデータを同期できるようにするには、ユーザーが Google Health モバイルアプリにログインして、Google Health を Google アカウントにリンクする必要があります。OAuth 同意前に Google Health をリンクするをご覧ください。Google OAuth 2.0 は同意時に有効な Google アカウントを認証するため、有効な Google Health プロファイルがまだないアカウントをブロックすることはできません。
ユーザーが Google Health プロフィールを作成する前、または以前の Fitbit アカウントを Google アカウントに移行する前に Google OAuth の同意を完了した場合、users.getIdentity またはデータ エンドポイントを呼び出すと、ステータス FAILED_PRECONDITION、理由 ACCOUNT_NOT_LINKED の HTTP 400 Bad Request エラーが返されます。
{
"error": {
"code": 400,
"message": "The account is not linked to Google Health.",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "ACCOUNT_NOT_LINKED",
"domain": "health.googleapis.com",
"metadata": {
"redirect_uri": "https://fitbit.google.com/auth/signup"
}
}
]
}
}
アカウントへのアクセスを確認してこのエラーを処理するには:
- OAuth 認証コードをトークンと交換し、アプリの UI でアカウントをリンク済みとしてマークする前に、すぐに
users.getIdentity(GET https://health.googleapis.com/v4/users/me/identity)を呼び出します。 users.getIdentityまたはバックグラウンド データ同期呼び出しが、理由ACCOUNT_NOT_LINKEDで HTTP400を返した場合、アカウントを接続済みとしてマークしないでください。ユーザーが以前の Fitbit Web API から移行する場合は、既存の Fitbit 接続を有効のままにし、以前の Fitbit トークンを取り消さないでください。Google Health または Fitbit のアカウントを作成したことがない新規ユーザーと、Google アカウントにまだ移行していない既存の Fitbit ユーザーの両方に対応する、操作可能なプロンプトを表示します。
「お使いの Google アカウントは Google Health にまだリンクされていません。Google Health モバイルアプリを開き、Google アカウントでログインしてプロフィールを作成するか、既存の Fitbit アカウントを Google アカウントに移行してから、ここに戻って接続してください。」
エラー メタデータ(
https://fitbit.google.com/auth/signup)からredirect_uriを開く行動を促すフレーズのボタンを提供するか、以前の Fitbit ユーザーを Fitbit アカウントの移行に関するヘルプ記事に誘導します。
過去のデータのバックフィル
以前のエンドポイントが廃止される前にユーザーが新しい Google Health API エンドポイントで認証を行わなかった場合でも、デバイスと Google Health アプリの同期を継続している限り、ユーザーのデータは引き続き利用できます。ただし、このユーザーのデータにギャップが生じる可能性があります。
データをバックフィルするには、ユーザーが新しいエンドポイントに再認証した後、Google Health API を使用して過去のデータをバックフィルします。ガイダンスについては、過去のデータにクエリを実行するをご覧ください。
Sample の移行とリンクの実装例
次のリファレンス実装は、OAuth コールバックの処理、部分的またはゼロの同意の検証、users.getIdentity を使用したユーザー ID の解決(HTTP 400 ACCOUNT_NOT_LINKED 処理を含む)、以前の Fitbit トークンの取り消しによる二重リンクの防止、oauth_type を使用したデータ リクエストのルーティングを行う方法を示しています。
import requests
GOOGLE_HEALTH_IDENTITY_URL = "https://health.googleapis.com/v4/users/me/identity"
FITBIT_REVOKE_URL = "https://api.fitbit.com/oauth2/revoke"
DEFAULT_SIGNUP_URL = "https://fitbit.google.com/auth/signup"
def complete_google_health_linking(user_record: dict, oauth_token_response: dict, fitbit_client_creds: str) -> dict:
"""Completes Google Health account linking and migrates legacy Fitbit users."""
# 1. Check granted scopes (handle zero consent and partial consent)
granted_scopes = set(oauth_token_response.get("scope", "").split())
health_scopes = {s for s in granted_scopes if s.startswith("https://www.googleapis.com/auth/googlehealth")}
if not health_scopes:
return {
"status": "MISSING_PERMISSIONS",
"ui_action": "ROUTE_TO_MISSING_PERMISSIONS_SCREEN",
"message": "At least one permission is required to connect to Google Health.",
}
access_token = oauth_token_response["access_token"]
# 2. Call users.getIdentity and handle HTTP 400
# (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED").
identity_resp = requests.get(
GOOGLE_HEALTH_IDENTITY_URL,
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=10,
)
if identity_resp.status_code == 400:
error_payload = identity_resp.json().get("error", {})
if error_payload.get("status") == "FAILED_PRECONDITION":
for detail in error_payload.get("details", []):
if detail.get("reason") == "ACCOUNT_NOT_LINKED":
redirect_uri = detail.get("metadata", {}).get("redirect_uri", DEFAULT_SIGNUP_URL)
return {
"status": "ACCOUNT_NOT_LINKED",
"ui_action": "PROMPT_LINK_GOOGLE_HEALTH_ACCOUNT",
"redirect_uri": redirect_uri,
"message": (
"Your Google Account isn't linked to Google Health yet. "
"Open the Google Health mobile app and sign in with your Google Account "
"to create a profile, or move your existing Fitbit account to your "
"Google Account, then return here to connect."
),
}
identity_resp.raise_for_status()
identity = identity_resp.json()
# 3. Verify legacyUserId and map legacyUserId -> healthUserId.
previous_oauth_type = user_record.get("oauth_type")
legacy_fitbit_refresh_token = user_record.get("fitbit_refresh_token")
existing_legacy_id = user_record.get("legacy_user_id")
returned_legacy_id = identity.get("legacyUserId")
legacy_id_verified = bool(returned_legacy_id) and (
not existing_legacy_id or returned_legacy_id == existing_legacy_id
)
if previous_oauth_type == "fitbit" and not legacy_id_verified:
return {
"status": "LEGACY_ID_MISMATCH",
"ui_action": "PROMPT_VERIFY_FITBIT_MIGRATION_ACCOUNT",
"message": (
"The Google Account you signed in with does not match your linked "
"Fitbit account. Sign in with the Google Account linked to your "
"Fitbit profile."
),
}
# 4. Cut over oauth_type and revoke legacy Fitbit token once verified.
user_record.update({
"health_user_id": identity.get("healthUserId") or user_record.get("health_user_id"),
"legacy_user_id": returned_legacy_id or existing_legacy_id,
"google_access_token": access_token,
"google_refresh_token": oauth_token_response.get("refresh_token"),
"granted_scopes": list(health_scopes),
"oauth_type": "google",
"fitbit_access_token": None,
"fitbit_refresh_token": None,
})
if previous_oauth_type == "fitbit" and legacy_fitbit_refresh_token:
requests.post(
FITBIT_REVOKE_URL,
headers={
"Authorization": f"Basic {fitbit_client_creds}",
"Content-Type": "application/x-www-form-urlencoded",
},
data={"token": legacy_fitbit_refresh_token},
timeout=10,
)
return {
"status": "CONNECTED",
"health_user_id": user_record["health_user_id"],
"granted_scopes": user_record["granted_scopes"],
}
コミュニケーションとタイミング
ユーザーが既存の Fitbit OAuth から新しい Google OAuth に移行できるようにするには、次のベスト プラクティスに沿って対応してください。
価値を重視したコミュニケーション
「API を更新しました」と伝えるのではなく、Google Health データをアプリに統合するメリットを伝えます。ただし、データを同期するには再認証が必要であることをユーザーに認識してもらう必要があります。
- 統合によってアプリで利用可能になる機能を明確に説明し、それらの機能からどのようなメリットが得られるかが伝わるようメッセージを工夫します。
- 技術的な実装の詳細ではなく、機能に焦点を当て、ユースケースを提供します。
- 言わないこと: 「Fitbit API に接続できなくなります。」
- 推奨される表現: 「心拍数データを含む詳細なワークアウトを引き続き表示するには、Google Health API に再度同意してください。」
ユーザーに通知するタイミング
ユーザーとのすべてのコミュニケーションにおいて、Google Health のブランド ガイドラインを遵守し、閉じることができるバナー、カード、アラートを使用します。
- ユーザーがワークアウト中または手動で何かを記録しているときに、再同意画面をトリガーしないでください。
- 再同意を必須にするのは、数週間にわたって警告を表示した後、Fitbit Web API の正式なサポート終了期限に合わせて行うようにしてください。
- ユーザーがハード カットオフ後に再同意していない場合は、適切な復元パスを提供します。バナー、カード、ツールチップにヘルプ メッセージを表示して、データが欠落している理由とその修正方法をユーザーが理解できるようにします。
OAuth トークン付与レート制限を計画する
既存の Fitbit ユーザーが Google Health API に再度同意すると、各ユーザーの認可は Google Cloud プロジェクトの OAuth トークン付与レート制限にカウントされます。この上限は、1 分あたりおよび 24 時間のスライディング ウィンドウあたりにアプリを承認できるユーザー数を制御します。
移行中に 24 時間のスライディング ウィンドウ内で 10,000 人のユーザー登録または再認証を超えると予想される場合は、次の手順に沿って OAuth レート制限に達しないようにします。
- Google Cloud プロジェクトでトークン付与の使用状況をモニタリングします。
- 1 日の付与上限を超えないように、アプリ内移行通知のペースを調整します。
- 多数のユーザーに再認証を求める前に、OAuth トークン付与の割り当ての増加をリクエストします。使用状況を確認して増加をリクエストする手順については、OAuth アプリケーションのレート制限をご覧ください。