为确保所有用户都能公平地使用 Google Calendar API,我们设置了配额。使用日历 API 时,需要考虑以下三个重要限制:
- 我们将按项目和每个用户实施 API 用量配额。如需了解详情,请参阅下一部分。
- 一般日历用量限制:避免达到日历使用限制。
- 操作限制:您可能随时可能会受到速率限制。例如,如果您尝试连续快速写入单个日历。
日历 API 用量配额的类型
强制执行两种类型的配额:
- 每个项目每分钟:这是您的 Google Cloud 项目发出的请求数。
- 每个用户每个项目每分钟:这是您的 Cloud 项目中任何特定用户发出的请求数。此限额旨在帮助您确保在用户之间公平分配用量。
配额是每分钟使用滑动窗口计算的,因此如果流量在一分钟内快速突发超出每分钟配额,则会导致下一个窗口期的速率限制,以确保平均用量不超出配额。
如果超出上述任一配额,您将受到速率限制,并且会在查询中收到 403 usageLimits
状态代码或 429 usageLimits
状态代码。如果出现这种情况,您可以采取以下措施:
申请增加配额
如需查看或更改项目的用量限额,或申请增加配额,请执行以下操作:
- 如果您的项目还没有结算账号,请创建一个。
- 在 API 控制台中访问 API 库中的“已启用的 API”页面,然后从列表中选择一个 API。
- 如需查看和更改配额相关设置,请选择配额。如需查看使用量统计信息,请选择使用量。
使用指数退避算法
如果我们希望您降低请求速率,我们将返回 403“usageLimits”响应或 429 响应(请参阅完整的错误文档)。这不是严重错误,我们希望您在短暂的时间间隔后重试请求。如果请求仍然过快到达,我们会再次询问,依此类推。为使此功能正常运行,请求之间的延迟会随着时间的推移而增加。
通常,您应该使用截断指数退避算法;Cloud Storage 文档详细介绍了其工作原理和首选算法。如果您使用的是 Google 客户端库,系统通常会为您完成此流程;请参阅库文档。通常,您应该使用库实现,而不是自行编写实现。
随机选择流量模式
日历客户端容易出现由多个客户端同时执行操作而导致的流量激增。例如,对于日历客户端,一种常见的不良做法是在午夜执行完全同步。这几乎肯定会导致超出每分钟配额,并导致速率限制和退避。
为避免出现这种情况,请确保您的流量尽可能分布在一整天中。如果您的客户端需要执行每日同步,请让客户端确定一个随机时间(每个客户端的时间各不相同)。如果您需要定期执行操作,请将间隔时间设为 +/- 25%。这将更均匀地分配流量,并提供更好的用户体验。
使用推送通知
一个常见的用例是,每当用户日历发生变化时,都需要执行操作。这里的反模式是反复轮询感兴趣的每个日历。这将很快用完您的所有配额 - 例如,如果您的应用有 5,000 位用户,并且每分钟对每个用户的日历进行一次轮询,则需要的每分钟配额至少为 5,000,即使在任何工作完成之前也是如此。
服务器端应用可以注册推送通知,以便我们在发生感兴趣的事件时通知您。这些配置需要更多设置工作,但可让您更高效地利用配额,并提供更好的用户体验。请务必指定您想接收哪个 eventType
的通知。如需了解详情,请参阅推送通知。
通过服务帐号进行正确核算
如果您的应用使用全网域授权执行请求,则默认情况下,系统根据“每位用户每个项目每分钟”配额(而不是您模拟的用户)对服务帐号收费。这意味着,即使服务帐号可能在多个用户的日历上运行,它也可能会用尽配额并受到速率限制。为避免这种情况,您可以使用 quotaUser
网址参数(或 x-goog-quota-user
HTTP 标头)来指示向哪个用户收取费用。该配额仅用于计算配额。如需了解详情,请参阅 Cloud 文档中的限制每个用户的请求数。
测试配额限制处理
为确保您的应用在实践中可以顺利达到配额限制(例如,通过使用指数退避算法进行重试),并尽量减少对用户造成的任何潜在干扰,我们强烈建议您在真实环境中对此场景进行测试。
为了避免此类测试干扰您的实际应用使用,我们建议您在 Google API 控制台中注册一个单独的仅供测试用的项目,并以类似于生产项目的方式配置该项目。然后,您可以为此项目人为设置较低的配额,并观察应用的行为。
价格
Google 日历 API 的所有使用均无需额外付费。超出配额请求限制不会产生额外费用,也不会对您的账号收取费用。