Directory API：限制和配额

限制和配额可保护 Google 基础架构免受以不当方式使用 Directory API 的自动化流程所造成的影响。来自某个 API 的过多请求可能是由无害的拼写错误导致的，也可能是由于系统设计效率低下、进行不必要的 API 调用造成的。无论是什么原因，在来自特定来源的流量达到特定水平后，您都必须将其屏蔽，这样才能保证 Google Workspace 系统的整体健康状况。它可以确保一个开发者的行为不会对更广泛的社区产生负面影响。

在极少数情况下，如果您的 API 请求失败，则 API 会返回 HTTP 状态代码和错误原因。此外，响应正文还将详细说明出错的原因。

以下列表显示了达到配额限制所导致的错误的可能错误代码、原因、相应说明和建议的操作。

代码 原因 说明 建议采取的措施
403 userRateLimitExceeded 表示已超出用户速率限制。Google Cloud 控制台中设置的默认值是每个 Google Cloud 项目每个用户每分钟 2,400 次查询。 在 Google Cloud 项目的 Admin SDK API“配额”页面中提高每位用户限制，或使用指数退避算法减慢您发送请求的速率。
403 quotaExceeded 表示已达到特定操作的并发请求数量上限。 使用指数退避算法重试。您需要降低发送请求的速率。
429 rateLimitExceeded 表示已达到特定操作的并发请求数量上限。 使用指数退避算法重试。您必须降低发送请求的速率。 此限制针对每个 Google Workspace 帐号，而非每个 API 客户端或每个用户。此限额无法提高。

实现指数退避

指数退避是指客户端按照不断增加的时间间隔定期重试失败的请求的过程。这是网络应用的标准错误处理策略。使用指数退避算法可提高带宽使用效率、减少获得成功响应所需的请求数，并最大程度地提高并发环境中的请求吞吐量。

实现简单指数退避的流程如下。

  1. 向 API 发出请求
  2. 接收错误响应，其中包含一个可重试的错误代码
  3. 等待 1 秒 + random_number_milliseconds 秒
  4. 重试请求
  5. 接收错误响应，其中包含一个可重试的错误代码
  6. 等待 2 秒 + random_number_milliseconds 秒
  7. 重试请求
  8. 接收错误响应，其中包含一个可重试的错误代码
  9. 等待 4 秒 + random_number_milliseconds 秒
  10. 重试请求
  11. 接收错误响应，其中包含一个可重试的错误代码
  12. 等待 8 秒 + random_number_milliseconds 秒
  13. 重试请求
  14. 接收错误响应，其中包含一个可重试的错误代码
  15. 等待 16 秒 + random_number_milliseconds 秒
  16. 重试请求
  17. 如果错误仍然出现，则停止重试并记录错误。

在上述流程中，random_number_milliseconds 是小于或等于 1, 000 的随机毫秒数。必须这样做才能在一些并行实现中避免某些锁定错误。每次等待后，必须重新定义 random_number_milliseconds。

注意：等待时间始终是 (2 ^ n) + random_number_milliseconds，其中 n 是单调递增的整数，初始值为 0。n 在每次迭代（每次请求）后递增 1。

该算法设置为 n 为 5 时终止。设置此上限只是为了阻止客户端无限重试。总延迟约为 32 秒，请求才会被视为“不可恢复的错误”。如果需要，您的 API 客户端可以增加尝试次数。

API 限制和配额

API 限制类别 限制
创建用户 使用 Directory API 时，每个网域每秒创建的用户不能超过 10 个。
已将群组作为成员添加到其他群组 下级群组的成员最长可能会延迟 10 分钟才会显示为上级群组成员。此限制可能因系统容量而异。
移动设备

使用 Directory API，您最多可以执行以下操作：

  • 每秒 20 个操作请求。
  • 每秒 20 个删除请求。
  • 每秒 10 次 get 请求。
  • 每秒 10 个列表请求。
重命名用户 最长可能需要 10 分钟才能在所有服务中传播。在重命名用户之前，建议您先从所有浏览器会话和服务中退出该用户。有关详情，请参阅更新用户。
创建/更新组织部门
  • 使用 Directory API 时，每位客户每秒创建/更新的组织部门数量不得超过 1 个。
  • 客户的组织部门层次结构限定为 35 个层级。
  • 每个客户的组织部门总数不得超过 40,000。
API 配额类别 配额
Chrome 设备 annotatedLocation，字符数上限 设备位置信息的字符数上限为 200。
Chrome 设备 notes，字符数上限 设备备注信息的字符数上限为 500。
Chrome 设备，最多 user 个字符 设备用户名称的字符数上限为 100。
网域别名，数量上限 网域别名最多可以有 20 个。
群组、说明 说明中的字符数上限为 4,096。
每个账号的群组数 如果您使用 G Suite 免费版（旧版）帐号，则最多可有 10 个群组。其他版本对群组数量没有限制。
群组，每个群组的成员数量 如果使用 G Suite 免费版（旧版）帐号，一个群组最多可以包含 100 名成员。其他版本对单个群组可拥有的成员数量没有限制。 如需了解每位用户的群组成员资格限制，请参阅了解群组政策和限制
maxResults 查询字符串 该 API 会返回：
  • Chrome 和移动设备 - 默认设置为每页最多 100 个条目。
  • 群组和群组成员 – 默认设置为每页最多 200 个条目。
  • 用户 – 默认为 100 个条目，每页最多 500 个条目。
用户别名和组织部门资源不使用响应分页。系统会按字母顺序返回所有用户的主要电子邮件地址，并且响应顺序不区分大小写。
多个域名，一个账号中允许的域名数量上限 600（1 个主域名 + 599 个其他域名）
组织部门，一次可移动的用户数量上限 一次可移动 20 位用户。此外，用户的主电子邮件地址必须已存在于账号中。
用户别名 每个用户帐号最多可以有 30 个别名。
用户别名（使用已删除的别名） 已删除的用户别名可以立即再次使用。

其他类型的限制 限制和准则
结算和创建用户 对于 Google Workspace 弹性方案用户，使用此 API 创建用户会影响费用，并且还会向您的客户结算帐号收取费用。例如，如果您为 Google Workspace 采用的是弹性方案，那么创建 10 位用户后，系统将根据创建完毕的时间按比例向您的帐号收取 10 个 Google Workspace 许可的费用。如果您采用的是包年方案，那么您已经承诺要预先支付一定数量的许可，并且您只能根据承诺创建任意数量的用户。如需详细了解结算方案和结算账号，请参阅管理帮助中心。
姓名 姓氏和名字不得超过 40 个字符。它们支持 Unicode/UTF-8 字符，可以包含空格、字母 (a-z)、数字 (0-9)、短划线 (-)、正斜杠 (/) 和句点 (.)。要详细了解字符使用规则，请参阅管理帮助中心。
网上论坛，正在删除 删除群组不会删除该群组成员的用户帐号。
群组和群组成员，电子邮件地址更改 在此版本的 API 中，您可以在启用 Google Workspace 服务之前更改群组的电子邮件地址。使用管理控制台更改群组成员的电子邮件地址。更改后，API 会自动反映电子邮件地址的更改。
群组、设置 您可以通过管理控制台管理群组访问权限设置、共享选项、监控和讨论归档。要详细了解群组设置，请参阅管理帮助中心。
群组、发送消息 为防止垃圾邮件和电子邮件滥用情况，Google 会限制您一次可以向外部收件人发送的邮件数量。如果您向群组发送邮件，则每个外部成员都算作一个收件人。有关详情，请参阅电子邮件发送上限和防止发送给 Gmail 用户的邮件遭到屏蔽或被列为垃圾邮件 。
群组，发送 NDR 邮件 您不能将无法递送回执（NDR，也称为“退回邮件”）发送或转发到群组。
由用户创建的群组、限制 有关用户创建的群组的限制，请参阅管理帮助中心
组织部门，启用/停用服务 使用管理控制台为组织部门管理服务启用和停用事宜。
密码 可以包含字符的任意组合。最少需要 8 个字符。长度上限为 100 个字符。
照片 在此 API 版本中，照片是用户最新的 Google 个人资料照片。
用户名 用户名可以包含字母 (a-z)、数字 (0-9)、短划线 (-)、下划线 (_)，并且 Google Workspace 可识别句点或句点 (.)。这与 Gmail 不同。用户名不得包含等号 (=)、尖括号（<、>）或一行中的多个英文句号 (.)。如需了解详情，请参阅管理帮助中心。
用户名、重命名 重命名后，Google Hangouts 会舍弃所有已保存的聊天邀请。用户必须再次请求获得与好友聊天的权限。旧用户名将作为电子邮件别名保留，以确保在电子邮件转发设置的情况下能够继续递送邮件，并且不能用作新用户名。如需详细了解重命名用户所产生的影响，请参阅管理帮助中心。在重命名后，使用删除用户的别名操作即可移除电子邮件别名。
多个网域中的用户 Google Workspace 帐号可以包含您的任何域名。在多网域帐号中，一个网域中的用户可以与其他帐号网域中的用户共享服务。多个网域组件包括：
  • 主域名 - 您帐号的主域名是接受《Google Workspace 服务条款》协议的管理员的域名。此网域是顶级组织部门的帐号级网域。注册 Google Workspace 账号时，我们建议您使用企业域名作为主域名，并将其他域名预留给试用和测试等专用用途。
    • 所有超级用户都可以管理整个帐号。
    • 该 API 无法更改或移动 Google Workspace 帐号的主域名。但是，该 API 可以重命名用户的帐号，将其电子邮件地址从一个域名更改为另一个域名。
    • 对于 Google Workspace 帐号，您有 21 天的时间来验证您对主域名的所有权。对于其他网域，您必须先验证网域所有权，然后才能将该网域用作用户的主电子邮件地址。在这种情况下，21 天的宽限期不适用。
    • 在此版本的 API 中，主网域的设置会应用于与该帐号关联的所有网域，但用户对 Google Workspace 服务的访问权限除外。
  • 其他帐号域 - 建立主域并设置帐号之后，您可以向帐号添加其他域。对于其他域名，请在设置该域名时验证您的所有权，然后再将该域名用作用户的主电子邮件地址。
  • 用户的主域 - 用户的主电子邮件地址中使用的域是用户的主域。此域名可以是帐号中的任何域名，包括主域名。
如需了解最新的多网域限制，请参阅多个网域限制。包括有关网域别名、帐号合并等信息。
警告，群组成员 GROUP_CANNOT_CONTAIN_CYCLE – API 不允许在群组成员资格中循环。例如，如果 group1 是 group2 的成员，则 group2 不能成为 group1 的成员。