Google Health API 資料類型

下表列出所有資料類型，並提供多個資料欄，協助您瞭解 Google Health API 中各類型的表示方式，以及各類型適用的範圍。

資料類型欄位

Google Health API 資料類型表格包含多個欄位，可協助您瞭解各資料類型的表示方式和需求。這些資料欄如下：

查詢限制

透過 API 查詢資料點、匯總或每日匯總時，請注意下列限制：

• 篩選條件：部分唯讀衍生資料類型 (例如 total-calories) 需要篩選條件，指定間隔開始時間 (使用實際或民事時間)。
• 查詢範圍限制：彙整和每日彙整聚合端點會根據資料類型，強制執行查詢範圍上限：
  • calories-in-heart-rate-zone、heart-rate、active-minutes 和 total-calories 的查詢範圍上限為 14 天。
  • 所有其他資料類型的查詢範圍上限為 90 天。
• 匯總視窗大小：呼叫 rollUp 端點時，windowSize 時間長度必須至少為 1 秒 ("1s")。如果時間長度不到 1 秒，系統會以 INVALID_ARGUMENT 拒絕。此外，請選擇windowSize大於或等於資料類型基礎儲存空間解析度的"60s"，例如 steps 和 distance 等 1 分鐘間隔資料類型，以免子間隔的分布不均。詳情請參閱「匯總視窗大小和基礎儲存空間解析度」。

每日與間隔資料類型

對於心率變異分析 (HRV) 或血氧濃度 (SpO2) 等特定生理指標，Google Health API 提供兩種不同的資料類型：每日版本和間隔版本。瞭解兩者差異，是根據用途選擇合適指標的關鍵：

• 每日：一整天的預先匯總摘要。使用這個檢視畫面可查看高階趨勢和每日資訊主頁，節省處理時間。

• 間隔：全天候進行精細的高解析度測量。您可以使用這項功能繪製當日波動圖表，或執行每小時的深入分析。

資料可用性

使用者必須同步活動追蹤器，或在 Fitbit 行動或網頁應用程式中手動輸入新資料，才能更新資料。如果 Fitbit 應用程式在行動裝置上開啟，且裝置與應用程式之間有作用中的資料連線並在藍牙範圍內，Fitbit 裝置和 Fitbit 行動應用程式每 15 分鐘就會自動同步一次。如果使用者使用 MobileTrack 追蹤活動，只要應用程式處於開啟狀態，MobileTrack 就會每小時同步一次。

查詢歷來資料

Google Health API 的主要優點之一，就是能夠追蹤使用者的運動表現，並長期監控健康指標。您可以查詢使用者記錄的資料，API 對應用程式可使用的歷史資料量沒有限制。

不過，查詢歷來資料時，仍須遵守標準速率限制。為管理系統穩定性及避免過多酬載，Google Health API 會使用自動分頁功能，並根據端點設定頁面大小。請注意下列界線和行為：

• 自動分頁：如果您查詢的資料範圍很長，API 只會傳回第一頁結果，最多為該端點的頁面大小上限，並附上 nextPageToken。您必須使用 nextPageToken 要求後續頁面。
• 變數頁面大小：上限取決於端點和資料類型。大多數資料類型的網頁大小上限為 10,000。 不過，對於 exercise 和 sleep 等特定資料類型，預設和最大網頁大小上限為 25。舉例來說，如果用戶端要求過去 10 年的所有睡眠資料，API 仍只會在第一頁傳回 25 個睡眠記錄。
• 匯總日期範圍限制：對於資料匯總和匯總端點 (例如 rollUp 和 dailyRollUp)，查詢日期範圍會根據資料類型受到限制：
  • calories-in-heart-rate-zone、heart-rate、active-minutes 和 total-calories 的日期範圍上限為 14 天。
  • 所有其他匯總資料類型的範圍上限為 90 天。

視應用程式需要的歷來資料量而定，如要擷取整個資料集，必須依序逐頁擷取。設計應用程式的資料同步程序時，請將這點納入考量。

為確保最佳效能並避免 API 錯誤，查詢歷來資料時請遵守下列準則：

分階段同步處理資料 (熱載入與冷載入)

• 初始「熱」載入：在主要載入序列期間，只擷取並算繪最近 7 到 14 天的資料。這樣一來，使用者就能立即看到資料，不必等待長時間執行的查詢。
• 背景「冷」載入：在主要 UI 算繪完成後，將較舊的歷來資料擷取作業委派給非同步的低優先順序佇列或背景程序。

匯總查詢分塊

• 由於匯總和每日匯總端點會強制執行日期範圍上限 (視資料類型而定，為 14 或 90 天)，因此您必須將大型的歷來匯總查詢，分解為這些上限內較小的連續間隔。
• 請安全地批次處理或依序執行這些子查詢，以免超出並行限制，並維持穩定的 UI 進度指標。

運用預先匯總的匯總資料

重新架構總覽資訊主頁和趨勢圖表，使用預先匯總的摘要端點 (例如 DailyRollUpDataPoints)。這會大幅減少後端的運算負荷，以及用戶端的網路傳輸時間。

彈性錯誤處理 (智慧重試)

• 遇到速率限制 (429 Too Many Requests) 和伺服器閘道逾時 (504 Gateway Timeout) 時，請實作嚴格的指數輪詢處理機制。請勿立即重試大型失敗的酬載。即時重試會加劇後端壅塞，並導致系統效能下降。

第三方存取權

Fitbit 裝置無法直接與第三方應用程式或服務通訊。這些裝置只能與 Fitbit 行動應用程式通訊及同步。

只要開啟 Fitbit 應用程式，裝置就會全天自動同步資料。如果藍牙已啟用，且應用程式在背景執行，裝置每 15 分鐘就會同步一次。完成同步程序後，第三方服務就能透過 Google Health API 存取資料。

距離標準

運動距離 (例如 elevationGainMillimeters) 會以公釐為標準單位，原因如下：

1. 維持資料精確度：使用公釐的最重要原因，是確保我們讀取及提供的資料不會失去任何精確度。使用公釐等精細單位，可讓我們以高精確度表示測量結果。
2. 標準化：毫米是我們服務中設計的標準單位。這種一致性可確保開發人員與 API 不同部分互動時，都能獲得一致的體驗。
3. 支援廣泛的測量系統：使用毫米等基本單位，開發人員就能輕鬆轉換為任何其他所選單位，無論他們使用的是公制、英制或其他測量系統。

晝長變化

為因應日光節約時間或旅行造成的每日時長變化，Health API 會優先處理使用者的時間。每個資料點都會儲存實際的 UTC 時間戳記，以及事件發生時有效的 UTC 時差。這樣一來，系統就能：

• 將事件對應至精確的實體時間點。
• 將時間修正為使用者的當地時區，以便進行匯總。

日光節約時間

日光節約時間結束時，時間會「往回調」，因此當天的時間會變成 25 小時，而當天的匯總資料也會包含 25 小時的資料。「春季前進」會導致民用日為 23 小時，時間會調回標準時間。

旅遊

跨時區旅行時，單一民事日期的實際長度可能會出現更明顯的差異。

使用 dailyRollUp 端點來調整時區差異。系統會根據使用者的當地時間，自動將資料歸因於記錄當天的日曆日期，即使時區有所變更，也能有效「縫合」當天的資料。