Google Health API は、デベロッパーが Fitbit ユーザーデータにクエリを実行できるように一から構築された新しい API です。これは単なるアップデートではなく、アプリの安全性と信頼性を確保し、将来の医療技術の進歩に備えるための戦略的な動きです。この API は、アプリを登録するための新しいコンソール、Google OAuth 2.0 のサポート、新しいデータ型、新しいエンドポイント スキーマ、新しいレスポンス形式をサポートしています。
このガイドは、既存の Fitbit Web API アプリを新しい Google Health API に移行するデベロッパーを支援することを目的としています。
移行のメリット
Google Health API を使用するメリットは次のとおりです。
- セキュリティの強化: Google のセキュリティに関するベスト プラクティスに準拠し、Google のセキュリティ、プライバシー、ID の標準に沿って対応します。
- 一貫性: データ形式、タイムゾーン、測定単位、エラー処理における従来の不整合を解消し、より直感的なデベロッパー エクスペリエンスを実現します。
- スケーラビリティと将来性: 将来の需要に対応できるように設計されており、gRPC などの最新のプロトコルをサポートしています。
アプリ登録
すべての Google Health API アプリは、すべての Google アプリを管理する中央ハブとして機能する Google Cloud コンソールを使用して登録する必要があります。
アプリを登録する手順については、スタートガイドの手順をご覧ください。アプリを登録する際に、以下の違いに気づくでしょう。
| Fitbit Web API | Google Health API | |
| 公開リンク | https://dev.fitbit.com/apps | https://console.cloud.google.com |
| 新しいアプリを追加する | [Register a new app] を押します。 |
|
| 基本情報 | 入力するフィールド:
|
入力するフィールド:
|
| アプリケーション タイプ | デベロッパーは、次の項目を選択する必要があります。
|
|
| クライアント ID | アプリケーションの設定が保存されたときに登録されます | 別途登録 |
| アクセスタイプ | 読み取り / 書き込みアクセスはアプリレベルで制御される | 読み取り / 書き込みアクセスはスコープレベルで制御される |
| 追加の URL |
|
|
OAuth の実装
Google Health API アプリは、Google OAuth2 クライアント ライブラリのみをサポートしています。クライアント ライブラリは一般的なフレームワークで利用できるため、OAuth 2.0 の実装が簡単になります。Google OAuth2 ライブラリとオープンソース OAuth2 ライブラリの違いは次のとおりです。
| Fitbit Web API | Google Health API | |
| OAuth2 ライブラリのサポート | オープンソース | Google OAuth2 クライアント ライブラリ |
| 機能 | プラットフォーム間で一貫性がない | プラットフォーム間で一貫性がある |
| 認可 URL | https://www.fitbit.com/oauth2/authorize | https://accounts.google.com/o/oauth2/v2/auth |
| トークン URL | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| Access Token Lifetime | 8 時間 | 1 時間 |
| アクセス トークンのサイズ | 1,024 バイト | 2,048 バイト |
| 更新トークン | 更新トークンは、認証コード権限付与フローを使用するときに生成されます。ユーザーに対して生成できる更新トークンは 1 つのみです。トークンは期限切れにならず、1 回しか使用できません。 | 更新トークンを生成するには、認可文字列にクエリ パラメータ「access_type=offline」が含まれている必要があります。1 人のユーザーに対して複数の更新トークンを作成できます。更新トークンは時間ベースにできます。6 か月間使用されていない場合、ユーザーが時間ベースのアクセス権を付与した場合、またはアプリが「テスト」モードになっている場合は、期限切れになります。詳しくは、更新トークンの有効期限をご覧ください。 |
| トークン レスポンス | JSON レスポンスには次のものが含まれます。
|
JSON レスポンスには次のものが含まれます。
ユーザー ID を取得するには、users.getIdentity エンドポイントを使用します。 |
ユーザーの再認証（再同意が必須）
アプリで別の OAuth ライブラリを使用しているため、Fitbit ユーザーは新しい統合に再度同意する必要があります。アクセス トークンと更新トークンを Google Health API に転送して機能させることはできません。
スコープ
Google Health API スコープを使用するように認証リクエストを更新する必要があります。スコープは、アプリが読み取りオペレーションと書き込みオペレーションのどちらをサポートするかを定義します。アプリに不要なスコープは使用しないでください。アプリの設計が変更された場合は、後でスコープを追加できます。
Google Health API のスコープは、https://www.googleapis.com/auth/googlehealth.{scope} で始まる HTTP URL です。例: https://www.googleapis.com/auth/googlehealth.activity_and_fitness。
スコープ マッピング
Fitbit Web API のスコープと Google Health API のスコープの対応は次のとおりです。
| Fitbit Web API のスコープ | Google Health API スコープ |
|---|---|
| アクティビティ | .activity_and_fitness .activity_and_fitness.readonly |
| cardio_fitness | .activity_and_fitness .activity_and_fitness.readonly |
| 心拍数 | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| ロケーション | .location.readonly |
| 栄養 | .nutrition .nutrition.readonly |
| oxygen_saturation | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| プロフィール | .profile .profile.readonly |
| respiratory_rate | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| 設定 | .settings .settings.readonly |
| sleep | .sleep .sleep.readonly |
| 温度 | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| weight | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
データ型
Google Health API のデータ型と Fitbit Web API へのマッピング方法のリストは次のとおりです。
| Fitbit Web API のデータ型 | Google Health API データ型 エンドポイント ID |
|---|---|
| アクティブ ゾーン時間 | アクティブ ゾーン時間active-zone-minutes
|
| ユーザーのアクティビティ レベルの変更が含まれます | アクティビティ レベルactivity-level
|
| 高度 | 高度altitude
|
| 体脂肪 | 体脂肪率body-fat
|
各心拍ゾーンの滞在時間: caloriesOut |
心拍ゾーン内の消費カロリーcalories-in-heart-rate-zone
|
| HRV の概要 | 1 日の心拍変動daily-heart-rate-variability
|
| 血中酸素ウェルネスの概要 | 1 日の酸素飽和度daily-oxygen-saturation
|
| 安静時の心拍数 | 1 日の安静時の心拍数daily-resting-heart-rate
|
| 皮膚温 | 毎日の睡眠時の体温の推移daily-sleep-temperature-derivations
|
| 距離 | 距離distance
|
| 記録されたアクティビティ | エクササイズexercise
|
| 階数 | 階数floors
|
| 心拍数 | 心拍数heart-rate
|
| HRV Intraday | 心拍変動heart-rate-variability
|
| 血中酸素ウェルネス（1 日を通して） | 酸素飽和度oxygen-saturation
|
| ユーザーがランニングしたときの VO2 最大値 | ランニング時の最大酸素摂取量run-vo2-max
|
| アクティビティの時系列（分） - 座りがち | Sedentary Periodsedentary-period
|
| 睡眠 | Sleepsleep
|
| 手順 | 手順steps
|
活動 caloriesOut |
総カロリーtotal-calories
|
| 最大酸素摂取量の値 | 最大酸素摂取量vo2-max
|
| 重量 | 重みweight
|
エンドポイント
REST エンドポイントでは、すべてのデータ型で一貫した構文が採用されています。
- サービス エンドポイント: ベース HTTP URL が https://health.googleapis.com に変更されます。
- エンドポイントの構文: Google Health API は、サポートされているデータ型のほとんどで使用できるエンドポイントを少数サポートしています。これにより、すべてのデータ型で一貫した構文が提供され、エンドポイントが使いやすくなります。
- ユーザー識別子: エンドポイント構文で、ユーザー ID または me のいずれかを指定する必要があります。me を使用する場合、ユーザー ID はアクセス トークンから推測されます。
例: Google Health API を使用して呼び出される GET Profile エンドポイントの例を次に示します。
GET https://health.googleapis.com/v4/users/me/profile
エンドポイント マッピング
使用可能なデータ型と、それらがサポートする API メソッドの一覧については、データ型の可用性の表をご覧ください。
| Fitbit Web API エンドポイント タイプ | Google Health API |
| 1 日分のデータをリクエストする GET（Log | Summary | Daily Summary） | windowSize = 1 日の dailyRollup メソッド |
| 詳細なデータをリクエストする GET（当日） | list メソッド |
| 日付または間隔で GET（時系列） | 日付範囲を含む rollUp メソッドまたは dailyRollUp メソッド |
| GET（ログリスト） | list メソッド |
| CREATE と UPDATE のログ | patch メソッド |
| ログを削除する | batchDelete メソッド |
| GET Profile | users.getProfile はユーザーの特定の情報を返します。 users.getSettings はユーザーの単位とタイムゾーンを返します。 |
| プロファイルを更新する | users.updateProfile はユーザーの特定の情報を変更します
users.updateSettings はユーザーの単位とタイムゾーンを変更します |
| ユーザー ID を取得する | users.getIdentity は、ユーザーの Fitbit の以前のユーザー ID と Google ユーザー ID を返します。 |
ユーザーを移行する
Fitbit Web API から Google Health API への移行は、単なる技術的な更新ではありません。OAuth ライブラリの変更により、ユーザーは新しい統合に再度同意する必要があります。アクセス トークンと更新トークンを Google Health API に転送して使用することはできません。移行中のユーザー維持を支援するため、移行を成功させるための技術的および戦略的な提案をいくつかご紹介します。
デュアル ライブラリ戦略
Fitbit Web API と Google Health API では異なる OAuth2 ライブラリを使用するため、両方のライブラリがコードベースに存在する「ブリッジング」期間を管理する必要があります。
Parallel Authorization Management
- クライアントをカプセル化する: 「Health Service」の抽象化レイヤまたはインターフェースを作成します。これにより、アプリの残りの部分で、特定のユーザーに対してどのライブラリ（Fitbit OAuth と Google OAuth）がアクティブであるかを認識せずにデータをリクエストできます。
- データベース スキーマの更新: ユーザー テーブルを更新して
oauth_typeフラグを含めます。たとえば、Fitbit OAuth にはfitbitを、Google OAuth にはgoogleを使用します。- 新規ユーザー: デフォルトで Google Health API と Google OAuth ライブラリが使用されます。
oauth_typeをgoogleに設定します。 - 既存のユーザー: 再同意フローを完了するまで Fitbit Web API を使用し続けます。
oauth_typeをfitbitに設定します。
- 新規ユーザー: デフォルトで Google Health API と Google OAuth ライブラリが使用されます。
「ステップアップ」再同意フロー
ログアウトを強制する代わりに、増分認証アプローチを使用します。
- Fitbit オープンソース トークンを検出: Fitbit Web API ユーザーがアプリを開いたときに、「サービス更新」通知をトリガーします。
- Google OAuth フローを開始する: ユーザーが [更新] をクリックしたら、Google OAuth2 ライブラリ フローを開始します。
- Replace & Revoke: Google OAuth トークンが正常に受信されたら、ユーザー プロファイルに保存し、
oauth_typeをfitbitからgoogleに更新して、（可能であれば）古いfitbitトークンをプログラムで取り消し、ユーザーのセキュリティ プロファイルをクリーンな状態に保ちます。
ユーザー維持率を最大化する
再同意は、解約の「危険ゾーン」です。ユーザーがアプリを離脱しないようにするには、次の UX のベスト プラクティスを参考にしてください。
「価値優先」のコミュニケーション
「API を更新しました」から始めないでください。Google が支援する新しいシステムのメリットを最初に説明します。
- セキュリティの強化: Google の業界をリードするアカウント保護と 2 要素認証について言及します。
- 信頼性: 同期時間の短縮とデータ接続の安定性の向上。
- 機能ゲーティング: 新しい機能とデータ型にはアップデートが必要であることをユーザーに優しく通知します。
スマート タイミング
- 価値の高いタスクを中断しない: ユーザーがワークアウト中や食事の記録中に再同意画面をトリガーしないでください。
- 「ナッジ」フェーズ: 最初の 30 日間は、閉じることのできるバナーを使用します。
- 「ハードカットオフ」フェーズ: 警告を数週間行った後、Fitbit Web API の正式な非推奨化の期限に合わせて、再同意を必須にします。
移行フローの比較
古いフローと新しいフローを明確に区別することで、ロジックが分岐する場所を開発者が理解しやすくなります。
| 機能 | Fitbit Web API（レガシー） | Google Health API（Google-Identity） |
| Auth ライブラリ | 標準オープンソース | Google Identity Services（GIS）/ Google Auth |
| ユーザー アカウント | Fitbit レガシー認証情報 | Google アカウント |
| トークンのタイプ | Fitbit 固有のアクセス / 更新 | Google が発行したアクセス トークンと更新トークン |
| スコープ管理 | 広範な権限 | きめ細かい権限 / 段階的な権限 |
アカウント移行のニュアンスを処理する
Fitbit のドキュメントによると、アカウントを Google に移行しても、通常はサードパーティとの接続がすぐに失われることはありませんが、API バージョンの変更はデベロッパー側の要件です。
- トークンの有効性を確認: バックグラウンド ワーカーを使用して、Fitbit トークンが「Unauthorized」エラーで失敗しているかどうかを確認します。これは、ユーザーがアカウントを移行したものの、アプリがそれに追いついていないことを示している可能性があります。
- グレースフル フェイルオーバー: Fitbit OAuth 呼び出しが失敗した場合は、新しい Google OAuth フローを明示的に使用するカスタムの [Fitbit を再接続] ページにユーザーをリダイレクトします。
サンプルコード
以前の Fitbit Web API から Google Health API に移行するには、一般的な OAuth2 ライブラリから Google Auth Library に移行します。以下に、この「デュアル ライブラリ」状態を処理するためのアーキテクチャの提案と、JavaScript で記述された擬似コードの実装を示します。
1. 「ミドルウェア スイッチ」
すべてのユーザーを一度に移行することはできないため、バックエンドでは、データベースに保存されているユーザーの現在の apiVersion に基づいて、使用するライブラリを決定する必要があります。
実装
const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;
// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
process.env.GOOGLE_CLIENT_ID,
process.env.GOOGLE_CLIENT_SECRET,
process.env.REDIRECT_URI
);
// 2. Create a Unified Fetcher
async function fetchSteps(user) {
if (user.apiVersion === 4) {
// ---- GOOGLE OAUTH LIBRARY LOGIC ----
GHAClient.setCredentials({ refresh_token: user.refreshToken });
const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
const res = await GHAClient.request({ url });
return res.data;
} else {
// ---- FITBIT WEB API LEGACY LOGIC ----
// Use your existing Fitbit open-source library logic here
return callLegacyV1Api(user.accessToken);
}
}
2. UX フローを移行する
保持率を最大化するには、「中断とアップグレード」パターンを使用します。これにより、ユーザーがアプリを操作するまで、再ログインを強制されることはありません。
リダイレクト ロジック
Fitbit Web API ユーザーが特定の機能にアクセスしたときに、移行をトリガーします。
app.get('/dashboard', async (req, res) => {
const user = await db.users.find(req.user.id);
if (user.apiVersion === 1) {
// Render a "soft" migration page explaining the Google transition
return res.render('migrate-to-google', {
title: "Keep your data syncing",
message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
});
}
const data = await fetchSteps(user);
res.render('dashboard', { data });
});
3. 主な技術移行
JavaScript 移行スクリプトを作成する際は、次の違いに注意してください。
| 機能 | Fitbit Web API（レガシー） | Google Health API（Google-Identity） |
| トークン エンドポイント | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| Auth ライブラリ | 標準オープンソース | Google の認証 |
| スコープ | アクティビティ | https://www.googleapis.com/auth/googlehealth.activity_and_fitness |
| ユーザー ID | /oauth2/token レスポンスで返される Fitbit エンコード ID | users.getIdentity エンドポイントから返されたユーザー ID |
4. 保持のチェックリスト
- セッションの永続性: Google Health API の access_token が正常に検証され、データベースに保存されるまで、ユーザーの古い Fitbit Web API セッションをクリアしないでください。
- 自動取り消し: Google Health API の移行が完了したら、POST リクエストを使用して、以前の Fitbit の取り消しエンドポイント（https://api.fitbit.com/oauth2/revoke）にアクセスします。これにより、Fitbit の設定に「重複した」アプリの権限が表示されなくなります。
- エラー処理: Fitbit の呼び出しで 401 Unauthorized が返された場合、エラー メッセージを表示する代わりに、Google OAuth フローに自動的にリダイレクトします。