Google Health API でのデータの操作は、クラウド内の Google Health API データストアと独自のアプリまたはバックエンド データストアの間でデータを同期するサイクルが基本となります。ただし、このサイクルはさまざまな要因によって異なる形式になることがあります。
- Google Health API にデータを書き込んでいますか？読み取り専用ですか？あるいは両方を行うべきか？
- データストアはアプリまたはデバイスのローカルにありますか？それとも、独自のクラウドですか？
- ユーザーのアプリとウェアラブル デバイスの間で Google Health API のデータを同期する必要がありますか？デバイスを同期する頻度はどのくらいですか？
- どのような種類のデータを扱っていますか？Basic のカウントはありますか？測定単位は？ サンプリング レートが異なる系列はありますか？
- アプリがバックグラウンドにあるときにデータを読み取る予定はありますか？
- アプリがユーザーの権限を取得する前に記録された過去のデータを処理する予定はありますか？
これらがどのように連携するかについては、Google Health API の同期ライフサイクルをご覧ください。このライフサイクルには、標準（読み取りと書き込み）と読み取り専用の 2 つのバージョンがあります。
標準同期のライフサイクル
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 を使用する場合は、サーバーから返されたリソース
nameまたは ID をデベロッパー データストアで抽出して永続化し、今後の更新（PATCH）または削除（DELETE）を可能にします。2 種類の ID について詳しくは、識別戦略をご覧ください。
読み取り
- レコードの読み取り - REST エンドポイント（
GETとfilterクエリ パラメータ、pageTokenページネーション、rollUpやdailyRollUpなどの集計エンドポイント）を使用して、Google Health API から新しいデータと既存のデータへの変更を取得するか、Webhook サブスクリプション（projects.subscribers）を使用してリアルタイム通知を受信します。通知は、新しいデータが利用可能であることを示すだけで、実際のデータの内容は示しません。 - デベロッパー データストアを調整する - 新しいデータと更新されたデータをデベロッパー データストアに調整します。
このサイクルは、外部デバイスやアプリの特定のニーズに応じて適切な間隔で繰り返されます。通常、独自のデータストアと Google Health API の間でデータを同期する場合は、この順序をおすすめします。
識別戦略
Google Health API にデータを書き込む場合は、Google Health API との統合を構築する前に、データポイント（データの基本単位）の作成時にリソース識別戦略を選択する必要があります。
現時点では、Health API で書き込み用のクライアント割り当て ID はサポートされていません。このような ID は POST で提供されることがありますが、無視されます。このオプションの詳細については、情報提供のみを目的としてこちらに記載しています。
- サーバー生成 ID（デフォルト オプション）: クライアントは ID なしでデータを送信し、Google Health API バックエンドは一意のシステム ID を生成して返します。
- クライアント割り当てのカスタム ID（AIP-133 に準拠、まだサポートされていません）: クライアント アプリは一意の識別子（UUID やローカル データベースの主キーなど）を生成し、作成時にリソースパスで提供します。
次の表に、2 つの識別戦略を比較します。この表を参考にして、統合に適したアプローチを選択してください。
| 機能 | サーバー生成 ID | クライアント割り当てのカスタム ID |
|---|---|---|
| ID の生成 | サーバーは POST の実行中にランダムなシステム ID を生成します。 |
クライアントは、書き込み前にローカルで安定した ID（UUID v4 / 内部 PK）を生成します。 |
| リソースパス | .../dataPoints/{server_id}（レスポンスで返される） |
.../dataPoints/{custom_id} |
| Post-Write Local Step | 必須。今後の更新や削除を可能にするため、返された 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 を選択する条件:
|
次のような場合はカスタム ID を選択します。
|
読み取り専用同期のライフサイクル
Google Health API からの読み取りのみを目的とするアプリは、データをデベロッパー データストアにコピーし、ライフサイクルの調整部分を処理する必要があります。
読み取りセクションで説明したタスクが、ここでも適用されます。
図 2 は、読み取り専用のライフサイクルを示しています。