最佳做法

授权

所有发送至 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。对于所有其他错误，重试请求可能并不适用。请确保您的请求具有幂等性，同时您可通过查看错误消息获取指导。

指数退避算法

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

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

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

合理使用 Google API

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

同步请求

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

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

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

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

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