限制和配额

限额和配额可保护 Google 的基础架构免受自动流程以不当方式使用 Reports API 所造成的影响。API 请求过多可能是由于无害的拼写错误所致,也可能是由于低效系统进行不必要的 API 调用所致。无论是何种原因,您都应在来自特定来源的流量达到某一级别时阻止该流量,这是保证 Google Workspace 系统总体运行良好所必需的。它可确保一个开发者的行为所造成的负面影响不会波及更大范围的开发者群体。

在极少数情况下,您的 API 请求会失败,此时您会收到 HTTP 状态代码响应。状态代码 403 包含有关输入有误的错误信息,而 HTTP 状态代码 503 包含指示哪些 API 配额已超出限额的错误信息。通过这些响应,您的自定义应用可以检测到这些错误并采取适当的操作。

如果您的请求需要在固定时间内完成,请并行发送请求,或在 Java 或 C# 应用中使用多个线程。并行请求的一个示例是请求来自不同用户的少量电子邮件,而不是同时添加或移除来自一位用户的许多电子邮件。对于线程,不妨先尝试 10 个线程,每个用户电子邮件地址对应一个线程。请注意,线程建议有利有弊,并非适用于所有 API 情况。如果请求数量过高,就会发生配额错误。

对于所有基于时间的错误(每个线程最多 N 个事物,持续 N 秒),尤其是 503 状态代码错误,我们建议您的代码捕获异常,并使用指数退避算法等待一小段时间,然后再重试失败的调用。一个线程的 Reports API 示例是等待 5 秒,然后重试失败的调用。如果请求成功,请针对其他线程重复此模式。如果第二个请求不成功,您的应用应减少请求的频率,直到成功进行一次调用。例如,将初始 5 秒延迟时间增加到 10 秒,然后再次重试失败的调用。此外,还要确定重试限制。例如,在应用向用户返回错误之前,重试请求 5 到 7 次,每次重试的延迟时间各不相同。

限制

API 限制类别 限制
报告 QPS 和 QPD 比率 该 API 会限制您的 Google Cloud 项目的请求数量。 Google Cloud 控制台中设置的默认值为每用户每分钟每个 Google Cloud 项目 2,400 次查询。您可以在 Google Cloud 项目的 Admin SDK API 配额页面中提高此限额。

如果超出这些限制,服务器会返回 HTTP 503 状态代码。重试请求时,请使用指数退避算法

activities.list 的其他限制 activities.list API 还有一项额外的限制,即每分钟最多 250 个过滤查询(每小时 15,000 个过滤查询)。 过滤查询是指包含以下至少一个查询参数的 API 请求:
  • userKey
  • actorIpAddress
  • eventName
  • filters
  • orgUnitID
  • groupIdFilter
API 配额类别 配额
maxResults API 响应的每个页面中列出的记录数介于 0 到 1000 条之间。默认值为 1000 条记录。

其他类型的限制

其他类型的限制 限制和准则
数据格式,默认 默认数据格式为 JSON。该 API 还支持 Atom 格式。
未经授权的请求 Google 不允许向 API 发送未经授权的请求。如果未提供授权令牌,则相应请求会被视为未经授权。如需了解详情,请参阅授权请求
警告消息
  • 数据不可用:相应应用和相应日期的数据不可用,并且将来也不会可用。
  • 部分数据可用:此应用和此日期的数据可能在未来可用。
如需了解 Reports API 的警告语法,请参阅面向客户用户的 API 参考文档。

针对 activities.list 的最佳实践

activities.list 方法预计将用于审核调查。 为获得最佳性能,您的请求应使用 startTimeendTime 参数包含时间范围。时间范围越窄,响应时间越短。 此方法不适用于批量检索审核日志。如果您经常用尽 activities.list 过滤条件请求配额,请考虑以下选项:

  • 设置 Google Workspace 日志导出到 BigQuery,并使用 BigQuery 强大的查询 API 来检索和分析所需的数据,而不会受到任何 API 配额限制。
  • 使用包含时间范围的非过滤请求,并执行客户端过滤(即在应用中实现过滤逻辑),而不是使用过滤请求。这样一来,您就可以突破每分钟 250 个过滤查询的限制,但仍需遵守每个 Google Cloud 项目中每位用户每分钟 2,400 个查询的限制。