设置 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 Cloud 项目，并希望将其用于 Google Health API，请确保您首先登录该项目的管理员账号。然后，点击该按钮后，从可用项目列表中选择现有项目。否则，请创建一个新项目。
  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 应用验证帮助中心。

监控 OAuth 令牌授予速率限制

Google Cloud 会对 OAuth 令牌授予强制执行速率限制，以控制应用可以多快的速度让用户登录或重新进行身份验证。如果您预计在 24 小时滑动窗口内会超过 10,000 个用户注册或重新身份验证，请提前申请更高的配额。如需了解详情，请参阅 OAuth 应用速率限制。

添加范围

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

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

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

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

更新范围

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

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

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

  2. 修改授权网址中的 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，因为后者会阻止通行密钥并破坏 Google OAuth 流程。如需指导，请参阅“使用 Google 账号登录”最佳实践。

用户在应用中完成 Google OAuth 2.0 权限请求流程之前，必须先登录 Google Health 移动应用，将 Google Health 关联到其 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_expires_in": 112154
}

何时刷新令牌

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

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

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

测试期间的令牌行为

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

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

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

生成示例数据

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

  • 佩戴智能手环：佩戴 Fitbit 智能手环、Pixel Watch 或其他与 Google Health 应用兼容的智能手表，然后四处走动，以生成步数、心率和锻炼数据。
  • 启用手机追踪：在 Google Health 应用中启用 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，请参阅使用跨账号保护功能保护用户账号。