管理配额

Google 日历 API 设有配额，以确保所有用户都能公平地使用该 API。 使用 Calendar API 时，需要考虑以下三项重要限制：

  • API 使用配额是按项目和按用户强制执行的。如需了解详情，请参阅下一部分。
  • 一般日历使用限制：避免超出日历使用限制。
  • 操作限制：您随时可能会受到速率限制。例如，如果您尝试快速连续写入单个日历。

日历 API 用量配额类型

系统会强制执行两种类型的配额：

  • 每分钟每个项目：这是您的 Google Cloud 项目发出的请求数。
  • 每位用户每个项目每分钟的请求数：这是您的 Cloud 项目中任何一位特定用户发出的请求数。此限制旨在帮助您确保用户之间的使用量分配公平合理。

配额是使用滑动窗口按每分钟计算的，因此，如果在一分钟内流量快速突增并超出每分钟配额，则在下一个窗口期间会进行速率限制，以确保平均而言，您的使用量保持在配额范围内。

如果超出任一配额，系统会限制您的查询速率，并向您返回 403 usageLimits 状态代码或 429 usageLimits 状态代码。如果发生这种情况，您可以采取以下措施：

  1. 请务必遵循所有最佳实践：使用指数退避、随机化流量模式、使用推送通知。
  2. 如果您的项目不断发展壮大，用户数量也在增加，您可以申请提高每个项目的配额。
  3. 如果达到每位用户的配额限制，您可以执行以下操作：
    • 如果您使用服务账号，请将负载分配给用户或在多个服务账号之间分摊负载。
    • 虽然您可以申请提高单用户配额，但一般不建议将其提高到高于默认值，因为您的应用可能会开始达到其他类型的限制，例如一般日历使用限制或操作限制。

申请增加配额

如需查看或更改项目的用量限制，或申请增加配额，请按以下步骤操作：

  1. 如果您的项目还没有结算账号，请创建一个。
  2. 在 API 控制台中访问 API 库中的“已启用的 API”页面，然后从列表中选择一个 API。
  3. 如需查看和更改配额相关设置，请选择配额。如需查看用量统计信息，请选择使用量。

使用指数退避算法

如果我们希望您降低请求速率，会返回 403“usageLimits”响应或 429 响应（请参阅完整错误文档）。 这不是致命错误，我们希望您在短时间间隔后重试请求。如果请求的到达速度仍然过快，我们会再次询问，依此类推。为了使此方法正常运行，请求之间的延迟时间必须随时间增加。

通常，您应使用截断指数退避算法；Cloud Storage 文档很好地说明了此算法的工作原理和首选算法。如果您使用的是 Google 客户端库，系统通常会为您处理此问题；请参阅您的库文档。通常，您应该使用库实现，而不是自行编写。

随机化流量模式

日历客户端容易出现流量高峰，这是因为多个客户端同时执行操作。例如，日历客户端的一个常见不良做法是在午夜执行完全同步。这几乎肯定会导致您超出每分钟配额，并导致速率限制和退避。

为避免出现这种情况，请尽可能确保流量在全天均匀分布。如果您的客户端需要每天同步一次，请让客户端确定一个随机时间（每个客户端的时间都不同）。如果您需要定期执行某项操作，请将间隔时间调整为 +/- 25%。这样可以更均匀地分配流量，并提供更好的用户体验。

使用推送通知

一个常见的使用情形是，每当用户日历中的内容发生变化时，都希望执行某项操作。一种反模式是反复轮询每个感兴趣的日历。这样会很快用完您的所有配额。例如，如果您的应用有 5,000 名用户，并且每分钟轮询每位用户的日历一次，那么即使在完成任何工作之前，每分钟也至少需要 5,000 的配额。

服务器端应用可以注册推送通知，以便在发生感兴趣的事情时通知您。虽然设置这些功能需要更多工作，但可以大幅提高配额使用效率，并提供更好的用户体验。请务必指定您要接收通知的 eventType。如需了解详情，请参阅推送通知。

使用服务账号进行适当的结算

如果您的应用使用全网域授权发出请求，默认情况下，服务账号会根据“每位用户每分钟每个项目”的配额收费，而不是您要模拟的用户。这意味着，即使服务账号可能在多个用户的日历上运行，也可能会用尽配额并受到速率限制。为避免出现此问题，您可以使用 quotaUser 网址参数（或 x-goog-quota-user HTTP 标头）指明将向哪个用户收取费用。此值仅用于配额计算。如需了解详情，请参阅 Cloud 文档中的限制每位用户的请求数。

测试配额限制处理

为确保您的应用能够在实践中妥善处理达到配额限制的情况（例如，通过使用指数退避算法进行重试），并尽可能减少对用户的潜在干扰，我们强烈建议您在真实环境中测试此场景。

为了避免此类测试干扰您的实际应用使用，我们建议您在 Google API 控制台中注册一个仅用于测试的项目，并以类似于生产项目的方式对其进行配置。然后，您可以为该项目设置人为的低配额，并观察应用的运行情况。

价格

Google Calendar API 可完全免费使用。超出配额请求限制不会产生额外费用，也不会向您的账号收取费用。