最佳做法

授权

所有发送至 Google 相册 API 的请求都必须由已通过身份验证的用户授权。

根据您所编写应用的类型,OAuth 2.0 的具体授权流程可能会略有不同。下面是适用于所有应用类型的大致流程:

  1. 按照以下操作准备授权流程:
    • 使用 Google API 控制台注册您的应用。
    • 启用 Google 相册 API 并获取 OAuth 详细信息(例如客户端 ID 和客户端密钥)。如需了解详情,请参阅使用入门
  2. 为访问用户数据,该应用会请求 Google 提供特定范围的访问权限。
  3. 对于要求授权应用请求某些数据的用户,Google 会向其显示同意页面。
  4. 待该用户同意后,Google 会为应用提供一个时效很短的访问令牌。
  5. 应用会请求获取用户数据,并在请求中附加访问令牌。
  6. 如果 Google 确定请求和令牌有效,就会返回您所请求的数据。

如需确定适合您应用的范围,请参阅授权范围

某些应用类型的流程还包括其他步骤,例如使用刷新令牌获取新的访问令牌。如需详细了解适用于各类应用的不同流程,请参阅使用 OAuth 2.0 访问 Google API

缓存

使数据保持最新状态。

如果出于性能原因需要临时存储媒体内容(如缩略图、照片或视频),根据我们的使用指南,请将其缓存时间限制在 60 分钟以内。

此外,您不应存储 baseUrls,该内容大约会在 60 分钟后过期。

唯一标识用户媒体库内容的媒体内容 ID 和影集 ID 不受缓存限制。您可以无限期存储这些 ID(受限于应用的隐私权政策)。您可以利用媒体内容 ID 和影集 ID,通过合适的端点再次获取可访问的网址和数据。如需了解详情,请参阅获取媒体内容列出影集

如果您要刷新多项媒体内容,更为高效的方法可能是存储返回媒体内容的搜索参数,并重新提交查询,从而重新加载数据。

SSL 访问

所有使用以下网址的 Google 相册 API 网络服务请求都必须使用 HTTPS:

https://photoslibrary.googleapis.com/v1/service/output?parameters

通过 HTTP 发出的请求将被拒绝。

错误处理

如需了解如何处理 API 返回的错误,请参阅 Cloud API 的处理错误部分。

重试失败的请求

指数退避算法中所述,客户端应在出现 5xx 错误时使用指数退避算法重试。除非另有说明,否则最小延迟应为 1 s

对于 429 错误,客户端在重试时的最小延迟可能为 30s。对于所有其他错误,重试请求可能并不适用。请确保您的请求具有幂等性,同时您可通过查看错误消息获取指导。

指数退避算法

在极少数情况下,您的请求可能会在传送时出错。您可能会收到 4XX5XX HTTP 响应代码,或者 TCP 连接可能会在客户端与 Google 服务器之间的某处出现错误。通常情况下,重试请求值得一试。首次请求失败后,后续请求可能会成功。但是,切勿进行循环操作,即反复向 Google 服务器发出请求。这种循环行为可能会使客户端与 Google 之间的网络过载,给多方造成问题。

较好的方法是不断增加两次重试之间的延迟。通常情况下,可利用乘积因子增加每次重试中的延迟,此方法称为指数退避算法

另请注意,在应用调用链中,并没有等级更高的重试代码可用于快速连续地发起重复请求。

合理使用 Google API

未经合理设计的 API 客户端可能会给网络和 Google 服务器增加额外负载。此部分包含适用于 API 客户端的一些最佳实践。遵循这些最佳实践有助于您的应用避免因无意中滥用 API 而遭到屏蔽。

同步请求

向 Google API 发起大量同步请求在行为上类似于对 Google 基础设施的分布式拒绝服务 (DDoS) 攻击,我们也将据此采取相应处理措施。为避免这种情况,请确保避免在客户端之间同步发起 API 请求。

例如,假设某应用显示当前时区的时间。此应用可能会在客户端操作系统中设置警报,并在分钟开始时唤醒该操作系统,以便更新显示时间。在处理与该警报相关的事务时,此应用不能调用任何 API。

但通过 API 调用来响应固定警报的做法并不妥当,因为这会导致 API 调用与分钟开始时间同步(即使在不同设备之间亦是如此),而非在一段时间内均匀分布。若应用未经合理设计,则此操作会导致在每分钟开始时产生正常水平 60 倍的流量。

相较之下,我们可以采用一种较好的设计,即将第二个警报设为随机选择的时间。当第二个闹钟触发时,应用会调用所需的任何 API 并存储结果。为了在分钟开始时更新其显示时间,应用会使用先前存储的结果,而非再次调用该 API。通过这种方式,API 调用将在一段时间内平均分配。此外,在更新显示画面时,API 调用也不会使显示延迟。

除了分钟开始时间,您还应注意不要设置其他常见同步时间,如小时开始时间和每天开始时间(午夜)。