設定 Google Cloud 和 OAuth

Google Health API 須透過 Google Cloud 存取。如要啟用 API 並授權 Google 帳戶，您需要 Google Cloud 專案。

無論您是現有的 Fitbit API 開發人員，還是剛接觸 Google Health API，都必須完成這個步驟，才能呼叫 API。

建立專案和 OAuth 用戶端

點選「Enable the API and get an OAuth 2.0 Client ID」(啟用 API 並取得 OAuth 2.0 用戶端 ID) 按鈕，啟用 Google Health API 並取得 OAuth 2.0 用戶端 ID：

  1. 如果您想將現有的 Google Cloud 雲端專案用於 Google Health API，請務必先登入該專案的管理員帳戶。然後點選按鈕，從可用專案清單中選取現有專案。否則，請建立新專案。
  2. 系統詢問「您從何處呼叫 API？」時，請選取「網路伺服器」。
  3. 在「Authorized redirect URIs」(已授權的重新導向 URI) 的值中輸入 https://www.google.com。必須提供重新導向 URI，才能使用 OAuth 2.0 取得授權碼。
  4. 設定完成後，複製 OAuth 2.0 用戶端 ID 和用戶端密鑰值，並將憑證 JSON 下載到本機電腦。
啟用 API 並取得 OAuth 2.0 用戶端 ID

如要手動設定 Google Cloud 雲端專案，或驗證設定並再次擷取憑證，請按照下列步驟操作：

  1. 在「API Enablement」頁面啟用 Google Health API。
  2. 在「憑證」頁面取得 OAuth 2.0 用戶端 ID。

如要進一步瞭解如何使用 Google 控制台設定 OAuth 2.0，請參閱「使用 OAuth 2.0 存取 Google API」。

使用不同的專案進行測試和正式環境

Google Health API 不提供獨立的沙箱或測試環境。所有環境都會呼叫正式版 Google Health API，因此您可以在 Google Cloud 雲端專案層級管理環境區隔。

為應用程式設定環境時，請遵循下列最佳做法：

  • 為開發、預備環境和正式環境建立獨立的 Google Cloud 雲端專案。每個專案都會管理自己的 OAuth 2.0 用戶端、同意畫面和 Webhook 訂閱者。
  • 請勿使用正式版 Google Cloud 雲端專案或其 OAuth 2.0 用戶端進行測試，因為對該專案所做的變更會直接影響正式版應用程式。
  • 請先在非正式環境專案中開發及測試，準備就緒後再將變更套用至正式環境專案。
  • 在 Google Cloud 控制台中使用標記，依環境區分專案。如需操作說明，請參閱「使用標記指定專案環境」。

新增測試使用者

根據預設，新建立的 OAuth 用戶端處於未驗證狀態，測試和正式環境的使用者人數上限為 100 人。如要在這段期間啟用授權，您必須在專案設定中，手動將每位使用者的電子郵件地址新增至測試使用者清單。

在「Audience」(目標對象) 頁面更新測試使用者名單：

  1. 在這個頁面中，「發布狀態」應設為「測試」，「使用者類型」應設為「外部」。
  2. 在「測試使用者」部分下方，按一下「+ 新增使用者」。輸入測試使用者的電子郵件地址，允許他們授予應用程式存取健康資料的權限。
  3. 按一下「儲存」。

如要透過 Google Health API 支援超過 100 位使用者，必須完成第三方安全性審查。詳情請參閱 OAuth 應用程式驗證說明中心。

監控 OAuth 權杖授予頻率限制

Google Cloud 會對 OAuth 權杖授予作業強制執行頻率限制，控管應用程式為使用者執行新進人員訓練或重新驗證的速度。如果預期 24 小時內的使用者註冊或重新驗證次數會超過 10,000 次，請事先申請提高配額。詳情請參閱「OAuth 應用程式頻率限制」。

新增範圍

您必須在「Data Access」(資料存取) 頁面上，指定用戶端可呼叫的範圍：

  1. 在這個頁面上，按一下「新增或移除範圍」。
  2. 在「API」欄中搜尋「Google Health API」。選取應用程式所需的範圍。
  3. 選取所需的所有範圍後，按一下「Update」(更新)，返回「Data Access」(資料存取權) 頁面。
  4. 按一下「儲存」。

選取範圍前，請先查看範圍實作。

您已完成用戶端 ID 設定，現在應該可以呼叫 Google Health API。

更新範圍

您可以在驗證要求中將提示參數設為同意，提示使用者重新授權應用程式。如果包含 prompt=consent，則每次應用程式要求存取範圍授權時，都會顯示同意畫面，即使先前已將所有範圍授予 Google API 專案也一樣。

如要使用 prompt=consent 參數新增或變更範圍，請按照下列步驟操作：

  1. 找出應用程式所需的完整範圍清單。這應包含現有範圍和任何需要新增的範圍。

  2. 修改授權網址中的範圍參數，加入以空格分隔的更新範圍值清單。

  3. 將 prompt=consent 附加至驗證 URI 參數。這會強制授權伺服器先提示使用者同意，再將資訊傳回用戶端。

    以下範例顯示向 Google 的 OAuth 2.0 授權端點發出的 HTTPS GET 要求，要求多個範圍並附加 prompt=consent：

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. 使用者點選更新後的連結時，系統會顯示同意聲明頁面，列出所有要求的範圍。使用者點選「繼續」或「允許」後，您會收到新的授權碼，可用來交換涵蓋完整範圍組合的權杖。

    只有在必要時才加入 prompt=consent，例如需要取得新的更新權杖，或要求的範圍已變更。

OAuth2 用戶端程式庫

如要查看可用於整合熱門架構的 OAuth2 用戶端程式庫清單，請參閱「使用 OAuth 2.0 存取 Google API」。

在行動或電腦版應用程式中導入 Google OAuth 時，請一律使用系統瀏覽器 (例如 Android 上的 Chrome 自訂分頁或 iOS 上的 ASWebAuthenticationSession)，切勿使用嵌入式 WebView，因為這會封鎖密碼金鑰，並中斷 Google OAuth 流程。請參閱「使用 Google 帳戶登入」功能最佳做法，瞭解相關指引。

使用者在應用程式中完成 Google OAuth 2.0 同意流程前，必須先登入 Google Health 行動應用程式，將 Google Health 連結至 Google 帳戶。Google OAuth 2.0 會驗證所有有效的 Google 帳戶，但無法在同意畫面中檢查帳戶是否有有效的 Google Health 設定檔。

請指示使用者先在 Google Health 行動應用程式中完成下列步驟，再於應用程式中啟動 OAuth 同意流程：

  1. 從 Google Play 商店或 Apple App Store 下載並開啟 Google Health 行動應用程式。
  2. 輕觸「使用 Google 帳戶登入」，然後選取要連結至應用程式的 Google 帳戶。
  3. 按照應用程式內提示建立新的 Google Health 個人檔案，或按照 Fitbit 帳戶遷移步驟，將現有 Fitbit 帳戶遷移到 Google 帳戶。

將授權碼換成 OAuth 權杖後，請呼叫 users.getIdentity 端點 (GET https://health.googleapis.com/v4/users/me/identity)，確認使用者的 Google 帳戶已連結至 Google Health，然後在應用程式中將帳戶標示為已連結。如要進一步瞭解如何處理未連結的帳戶 (400ACCOUNT_NOT_LINKED)，請參閱「處理未連結的 Google 帳戶」。

更新權杖

如要長期存取 Google API，且不需使用者持續重新驗證，應用程式必須使用更新權杖。如需完整的導入詳細資料，包括特定 HTTP 要求和必要參數，請參閱 Google Identity 平台說明文件。

如要將更新權杖換成存取權杖，請向 Google OAuth 2.0 權杖端點發出 HTTPS POST 呼叫。以下程式碼片段顯示要求和回應範例：

要求

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

回應

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token_expires_in": 112154
}

更新權杖的時機

當存取權杖過期或即將過期時，請在使用者有效工作階段的自然進程中，視需要更新權杖。避免批次更新權杖 (例如使用排定的 cron 工作或服務，在固定時間更新所有使用者的權杖)。

不建議批次更新權杖，原因如下：

  • 批次重新整理可避免權杖更新與活躍使用者同步模式一致。雖然您可以使用取得裝置呼叫查看使用者的上次同步時間，但這需要額外的 OAuth 範圍，使用者不一定要核准。
  • 批次處理會更新不需要重新整理的權杖，導致系統和 Google 伺服器產生多餘的處理負擔。
  • 如果在批次重新整理期間發生網路問題或伺服器服務中斷，所有受影響的使用者權杖都會同時受到影響。在使用者同步處理的自然進程中個別更新權杖，可將暫時性失敗的影響隔離至單一使用者。
  • 批次工作的問題較難診斷。由於批次要求發生的頻率較低，且會一次產生大量記錄項目，因此較難找出事件的開始時間。
  • 批次執行期間，權杖要求的高並行尖峰會增加達到頻率限制或發生間歇性驗證錯誤的可能性。

測試期間的權杖行為

請注意，更新權杖的行為會因 Google Cloud 專案的發布狀態而異：

  • 測試模式：如果 OAuth 同意畫面設為「測試」發布狀態，核發的更新權杖會以時間為依據，並在 7 天後到期。在這段期間，您會收到一個更新權杖，在到期日之前都有效，可用於取得新的存取權杖。
  • 發布模式：應用程式進入「正式版」狀態後，更新權杖通常不會過期，除非遭到撤銷或長期未使用 (通常為六個月)。

為提供流暢的使用者體驗，請務必先發布應用程式，再移至正式環境，以免權杖在 7 天後失效。

產生樣本資料

Google 不會提供預先填入的範例或模擬健康資料。如要測試整合，您必須自行產生測試資料。請使用下列任一方法，為測試使用者產生樣本資料：

  • 佩戴智慧手環：佩戴 Fitbit 智慧手環、Pixel Watch 或其他與 Google Health 應用程式相容的智慧手錶，然後四處走動，產生步數、心率和健身資料。
  • 啟用行動追蹤：在 Google Health 應用程式中啟用 MobileTrack，並帶著行動裝置四處走動。
  • 手動記錄資料：透過 Google Health 應用程式手動輸入健康指標，例如睡眠、體重、飲水量或食物攝取量。
  • 使用 API 寫入資料：直接將寫入要求 (例如 POST 或 PATCH) 傳送至 REST API 端點，以程式輔助方式填入資料。如要進一步瞭解如何建立及更新資料點，請參閱 REST 參考文件。

跨帳戶防護功能 (RISC API)

如要接收事件權杖或帳戶連結變更通知 (例如帳戶中斷連結或權杖撤銷)，請啟用風險和事件分享與協調 (RISC) 功能，以便清除儲存的權杖並更新 UI 連線狀態。您可以選擇是否啟用 RISC API。

如要為 Google Cloud 雲端專案啟用 RISC API，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中開啟「RISC API」頁面。請確認您已選取用於 Google Health API 的專案。
  2. 詳閱 RISC 條款，並確認您瞭解相關規定。
  3. 如果您同意條款，請點選「啟用」。

啟用 API 後，您必須建立並註冊 HTTPS 端點，才能接收及驗證 Google 傳送的事件權杖。

如要進一步瞭解跨帳戶防護功能和 RISC，請參閱「透過跨帳戶防護功能保護使用者帳戶」。