Google Health API 中的資料管理

使用 Google Health API 中的資料時，核心作業是在雲端 Google Health API 資料儲存庫與您自己的應用程式或後端資料儲存庫之間，同步處理資料。不過，這個週期會因多種因素而有不同形式：

• 您是否要將資料寫入 Google Health API？是否只能讀取？還是兩者都做？
• 資料儲存區是否位於應用程式或裝置的本機？還是您自己的雲端？
• 您是否需要在使用者應用程式和穿戴式裝置之間同步處理 Google Health API 資料？你多常同步裝置？
• 您處理哪些類型的資料？基本計數？測量單位？ 取樣率不同的序列？
• 您是否打算在應用程式於背景執行時讀取資料？
• 您是否打算使用應用程式取得使用者權限前記錄的歷來資料？

如要瞭解整體運作方式，請參閱 Google Health API 同步生命週期。這個生命週期有兩個版本：標準 (讀取和寫入) 和唯讀。

標準同步生命週期

圖 1：Google Health API 中的標準同步生命週期

整合 Google Health API 代表將資料複製到應用程式或後端資料存放區。為方便在本說明文件中使用，我們將這個資料儲存區稱為「開發人員資料儲存區」。

這裡的「複製」可以取代任何獨立活動，例如從 Google Health API 讀取資料 (複製到開發人員資料儲存庫)，或是寫入 Google Health API (複製到 Google Health API)。以特定順序重複執行這些動作，就是同步生命週期。

圖 1 說明標準同步生命週期，其中包含讀取和寫入作業，不考慮先前提及的任何因素。

寫入

1. 準備要寫入的新資料：從外部裝置或應用程式轉移資料，並將資料點格式化為與 Google Health API 資料類型相容的 JSON 表示法。請注意，健康資料 API 目前不支援寫入作業的自訂用戶端指派 ID。這類 ID 可能會出現在 POST 中，但系統會忽略這些 ID。
2. 新增或更新記錄：使用 REST 端點將資料點提交至 Google Health API。使用 POST 建立記錄，並使用 PATCH 插入及更新現有記錄。PATCH 作業所需的 ID 來自先前的 POST 作業 (前一週期的下一個步驟)。
3. 處理傳回的資源 ID - 使用伺服器產生的 ID 時，請在開發人員資料存放區中擷取並保存伺服器傳回的資源 name 或 ID，以便日後更新 (PATCH) 或刪除 (DELETE)。如要進一步瞭解這兩種 ID，請參閱識別策略。

讀取

1. 讀取記錄：使用 REST 端點 (GET 搭配 filter 查詢參數和 pageToken 分頁，或 rollUp 和 dailyRollUp 等匯總端點)，從 Google Health API 擷取新資料和現有資料的變更，或使用 Webhook 訂閱 (projects.subscribers) 接收即時通知。通知只會指出有新資料可用，不會顯示實際資料。
2. 協調開發人員資料儲存庫：將新資料和更新資料協調至開發人員資料儲存庫。

然後，這個週期會根據外部裝置或應用程式的特定需求，在適當間隔重複執行。一般來說，我們建議您按照這個順序，在自己的資料儲存庫和 Google Health API 之間同步資料。

識別策略

如要將資料寫入 Google Health API，請先選擇資源識別策略，再建立資料點 (基本資料單位)，然後與 Google Health API 整合。

健康資料 API 目前不支援寫入作業的用戶端指派 ID。 這類 ID 可能會以 POST 形式提供，但系統會忽略這些 ID。我們在此提供這項選項的詳細資料，僅供參考。

1. 伺服器產生的 ID (預設選項)：用戶端提交資料時不含 ID，Google Health API 後端會產生並傳回專屬的系統 ID。
2. 用戶端指派的自訂 ID (根據 AIP-133，尚未支援)： 用戶端應用程式會產生專屬 ID (例如 UUID 或本機資料庫主鍵)，並在建立時提供於資源路徑中。

下表比較兩種識別策略，協助您為整合項目選擇合適的做法：

功能	伺服器產生的 ID	客戶指派的自訂 ID
ID 生成	伺服器會在執行期間產生隨機系統 ID。POST	用戶端會在寫入前，在本機產生穩定 ID (UUID v4 / 內部 PK)。
資源路徑	.../dataPoints/{server_id} (在回應中傳回)	.../dataPoints/{custom_id}
撰寫當地內容後的步驟	必填項目。必須將傳回的 server_id 儲存在本機資料庫中，才能在日後更新/刪除。	無。應用程式已擁有該 ID。
ID 對應表	必填項目。用戶端必須維護雙向對應 (local_id ↔ server_id)。	不需要。用戶端直接使用自己的主鍵。
重試行為 (網路訊號微弱)	重複的風險。如果逾時後重試，系統會建立重複記錄，並指派新的伺服器 ID。POST	安全且具等冪性。使用相同的 custom_id 重試 POST，可避免重複建立 (傳回 409 ALREADY_EXISTS)。
離線同步支援	受限。必須等待伺服器回應，取得正式資源 ID，才能參照這些 ID。	完整。您可以使用穩定的 ID 離線建立及變動實體，然後在重新連線時順暢地同步處理。
格式限制	完全由伺服器處理。	必須遵循 ^[a-z0-9-]{4,63}$ (4 至 63 個小寫英數字元和連字號)。
選用時機	如果符合下列情況，請選擇伺服器產生的 ID： 您的應用程式只能寫入 / 附加資料 (例如傳送遙測或步數資料，且之後不會更新或刪除)。 應用程式不會維護個別資料點的本機永久資料庫。 您偏好簡單的驗證方式，不想管理字串驗證限制 (例如 4-63 個字元)。	在下列情況下，請選擇自訂 ID： 您操作雙向同步應用程式，可讀取、寫入及更新裝置上的健康記錄。 您的應用程式具有本機資料庫 (例如 Room 或 SQLite)，可儲存含有本機主鍵的記錄。 使用者在離線或行動網路連線不穩定的情況下記錄資料，因此需要安全重試。 您想消除後端資料庫和 API 之間的 ID 對應表。

唯讀同步生命週期

圖 2：Google Health API 中的唯讀同步生命週期

如果應用程式只打算從 Google Health API 讀取資料，就必須將資料複製到開發人員資料存放區，並處理生命週期的對帳部分。

「閱讀」一節中涵蓋的相同工作也適用於此。

圖 2 說明唯讀生命週期。