设置 Google Cloud 和 OAuth

Google Health API 的访问权限通过 Google Cloud 提供。如需启用 API 并授权 Google 账号，您需要一个 Google Cloud 项目。

无论您是现有的 Fitbit API 开发者，还是 Google Health API 的新手，都需要完成此步骤才能调用该 API。

创建项目和 OAuth 客户端

使用启用 API 并获取 OAuth 2.0 客户端 ID 按钮启用 Google Health API 并获取 OAuth 2.0 客户端 ID：

  1. 如果您有想要用于 Google Health API 的现有 Google Cloud 项目，请确保先登录该项目的管理员账号。然后，点击该按钮，从可用项目列表中选择现有项目。 否则，请创建一个新项目。
  2. 当系统询问“您从何处致电？”时，请选择网站服务器。
  3. 输入 https://www.google.com 作为授权重定向 URI 的值。必须使用重定向 URI 才能通过 OAuth 2.0 获取授权代码。
  4. 设置完成后，复制 OAuth 2.0 客户端 ID 和客户端密钥值，并将凭据 JSON 下载到本地机器。
启用 API 并获取 OAuth 2.0 客户端 ID

如果您想手动设置 Google Cloud 项目，或验证设置并再次检索凭据，请执行以下操作：

  1. 在 API 启用页面上启用 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 人。如需在此期间启用授权，您必须手动将每个用户的电子邮件地址添加到项目配置中的“测试用户”列表中。

在受众群体页面上更新测试用户列表：

  1. 在此页面上，您应该会看到“发布状态”设置为测试，“用户类型”设置为外部。
  2. 在“测试用户”部分下，点击 + 添加用户。输入应允许向您的应用授予健康数据访问权限的任何测试用户的电子邮件地址。
  3. 点击保存。

如果使用 Google Health API 的用户超过 100 人，则需要完成第三方安全审核。如需了解详情，请参阅 OAuth 应用验证帮助中心。

添加范围

您必须在数据访问页面上指定客户端可以调用的范围：

  1. 在此页面上，点击添加或移除范围。
  2. 在“API”列中，搜索“Google Health API”。选择应用所需的范围。
  3. 选择所有需要的范围后，点击更新返回“数据访问权限”页面。
  4. 点击保存。

在选择范围之前，请先查看范围实现。

您已完成客户端 ID 的设置，现在应该能够调用 Google Health API 了。

更新范围

您可以在身份验证请求中将 prompt 参数设置为 consent，以提示用户重新授权您的应用。如果包含 prompt=consent，则每次应用请求授权访问范围时，系统都会显示权限请求页面，即使之前已向您的 Google API 项目授予所有范围也是如此。

如需使用 prompt=consent 参数添加或更改范围，请按以下步骤操作：

  1. 确定应用所需的范围的完整列表。这应包括现有范围以及您需要添加的任何新范围。

  2. 修改授权网址中的 scope 参数，以包含以空格分隔的更新后的 scope 值列表。

  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，因为嵌入式 WebView 会阻止通行密钥并中断 Google OAuth 流程。如需相关指导，请查看“使用 Google 账号登录”最佳实践。

在用户通过您应用中的 Google OAuth 2.0 同意流程之前，必须先登录 Google 健康移动应用，将 Google 健康与其 Google 账号相关联。Google OAuth 2.0 会对任何有效的 Google 账号进行身份验证，但无法在权限请求页面上检查该账号是否具有有效的 Google Health 数据资料。

在您的应用中开始 OAuth 许可流程之前，请指示用户在 Google Health 移动应用中完成以下步骤：

  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，然后再将该账号标记为已在您的应用中关联。如需详细了解如何处理未关联的账号 (400 ACCOUNT_NOT_LINKED)，请参阅处理未关联的 Google 账号。

刷新令牌

如需长期访问 Google API 而无需用户不断重新进行身份验证，您的应用必须使用刷新令牌。如需了解全面的实现细节（包括所需的特定 HTTP 请求和参数），请参阅 Google Identity Platform 文档。

如需将刷新令牌换成访问令牌，请向 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": "refresh-token",
  "refresh_token_expires_in": 112154
}

何时刷新令牌

当访问令牌过期或即将过期时，在用户有效会话的自然进程中按需刷新令牌。避免批量刷新令牌（例如，使用预定的 cron 作业或服务在固定时间刷新所有用户的令牌）。

不建议批量刷新令牌，原因如下：

  • 批量刷新可防止将令牌更新与活跃用户同步模式对齐。虽然您可以使用 Get Devices 调用来查看用户的上次同步时间，但这需要额外的 OAuth 范围，用户无需批准。
  • 批量处理会更新不需要刷新的令牌，从而导致您的系统和 Google 服务器产生冗余的处理开销。
  • 如果批量刷新期间出现网络问题或服务器中断，所有受影响的用户令牌都会立即受到影响。在用户同步的自然进程中单独刷新令牌，可将暂时性故障的影响隔离到单个用户。
  • 对于批处理作业，诊断问题会更加困难。由于批量请求的发生频率较低，并且会一次性生成大量日志条目，因此很难精确定位突发事件的开始时间。
  • 在批处理运行期间，令牌请求出现高并发高峰会增加达到速率限制或遇到间歇性身份验证错误的几率。

测试期间的令牌行为

请注意，刷新令牌的行为取决于 Google Cloud 项目的发布状态：

  • 测试模式：如果您的 OAuth 权限请求页面配置为“测试”发布状态，则颁发的刷新令牌是基于时间的，会在 7 天后过期。在此期间，您将收到一个刷新令牌，该令牌在失效日期之前始终有效且可用于获取新的访问令牌。
  • 发布模式：应用进入“正式版”状态后，刷新令牌通常不会过期，除非被撤消或长时间（通常为六个月）未使用。

为确保用户体验顺畅，请务必在将应用移至生产环境之前发布应用，以免出现 7 天令牌过期的情况。

生成示例数据

Google 不提供预填充的健康数据样本或模拟健康数据。如需测试集成，您必须生成自己的测试数据。您可以使用以下任一方法为测试用户生成示例数据：

  • 佩戴手环：佩戴 Fitbit 手环、Pixel Watch 或其他与 Google 健康应用兼容的智能手表，然后四处走动，生成步数、心率和锻炼数据。
  • 启用移动设备追踪：在 Google 健康应用中启用 MobileTrack，然后携带移动设备四处走动。
  • 手动记录数据：通过 Google Health 应用手动输入健康指标（例如睡眠、体重、饮水或食物摄入量）。
  • 使用 API 写入数据：直接向 REST API 端点发送写入请求（例如 POST 或 PATCH），以通过编程方式填充数据。如需详细了解如何创建和更新数据点，请参阅 REST 参考文档。

跨账号保护 (RISC API)

如果您希望在发生以下情况时收到通知：活动令牌或账号关联发生更改（例如账号断开连接或令牌被撤消），请启用“风险和事件共享与协调”(RISC)，以便清理存储的令牌并更新界面连接状态。启用 RISC API 是可选的。

如需为您的 Google Cloud 项目启用 RISC API，请执行以下操作：

  1. 在 Google Cloud 控制台中打开 RISC API 页面。确保您用于 Google Health API 的项目处于选中状态。
  2. 阅读 RISC 条款，确保您了解相关要求。
  3. 如果您同意这些条款，请点击启用。

启用该 API 后，您必须创建并注册一个 HTTPS 端点，以接收和验证 Google 发送的事件令牌。

如需详细了解“跨账号保护”和 RISC，请参阅使用“跨账号保护”功能保护用户账号。