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 是一个小于或等于 1000 的随机毫秒数。必须这样做才能在一些并行实现中避免某些锁定错误。random_number_milliseconds 必须在每次等待后重新定义。

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

该算法设置为 n 为 5 时终止。设置此上限的目的仅在于防止客户端无限制地重试。此上限产生的结果是总延迟时间达到 32 秒左右才会将请求视为“不可恢复的错误”。如果需要，您的 API 客户端可以实现更多尝试次数。

API 限制和配额

API 限制类别 限制
创建用户 使用 Directory API 时，每个网域每秒最多只能创建 10 个用户。
删除用户 使用 Directory API，您每秒最多可以删除每个网域中的 5 位用户。这是每个网域的后端服务限制，无法在 Google Cloud 控制台项目配额中进行调整。发送批量请求时，请确保所有批次的总操作数保持在每秒查询次数 (QPS) 以下。
删除群组成员 使用 Directory API，您每秒最多可以删除每个网域中的 30 个群组成员。这是每个网域的后端服务限制，无法在 Google Cloud 控制台项目配额中进行调整。发送批量请求时，请确保所有批次的总操作数保持在每秒查询次数 (QPS) 以下。
群组已作为成员添加到另一个群组 下级群组的成员可能最长需要 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 条，最多每页 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 服务之前更改群组的电子邮件地址。使用 Google 管理控制台更改群组成员的邮箱。更改后，API 会自动反映电子邮件地址更改。
群组、设置 群组访问权限设置、共享选项、监控和讨论归档均通过 Google 管理控制台进行管理。如需详细了解群组设置，请参阅管理帮助中心。
群组，发送消息 为防范垃圾邮件和电子邮件滥用行为，Google 会限制您一次可向外部收件人发送的邮件数量。如果您向某个群组发送邮件，则每位外部成员都会被计为一位收件人。如需了解详情，请参阅电子邮件发信上限和防止发送给 Gmail 用户的邮件遭到屏蔽或被列为垃圾邮件。
群组，发送 NDR 邮件 您无法向群组发送或转发未递送回执 (NDR)，也称为“系统退信”。
用户创建的群组、限制 如需了解用户创建的群组的限制，请参阅管理帮助中心
组织部门，启用/停用服务 使用 Google 管理控制台为组织部门启用和停用服务。
密码 可以包含任意字符组合。密码长度至少为 8 个字符。长度上限为 100 个字符。
照片 在此版本的 API 中，照片是用户的最新 Google 个人资料照片。
用户名 用户名可以包含字母 (a-z)、数字 (0-9)、短划线 (-)、下划线 (_)，并且 Google Workspace 会识别点或英文句号 (.)。这与 Gmail 不同。用户名不得包含等号 (=)、尖括号（< 或 >）或一连串（超过 1 个）英文句号 (.)。如需了解详情，请访问管理帮助中心。
用户名、重命名 Google Hangouts 会在重命名后舍弃所有已记住的聊天邀请。用户必须请求权限才能再次与好友聊天。旧用户名会保留为邮箱别名，以确保在设置了邮件转发的情况下能继续递送邮件，并且无法用作新用户名。如需详细了解重命名用户的影响，请参阅管理帮助中心。重命名后，使用删除用户的别名操作移除邮箱别名。
多个网域中的用户 Google Workspace 账号可以包含您的任何域名。在多网域账号中，一个网域中的用户可以与其他账号网域中的用户共享服务。多个网域组件包括：
  • 主域名 -- 账号的主域名是指接受《Google Workspace 服务条款》协议的管理员的域名。此网域位于顶级组织部门的账号级。注册 Google Workspace 账号时，我们建议您将企业域名用作主域名，并将其他域名留作专门用途，例如试用和测试。
    • 所有超级用户都可以管理整个账号。
    • 该 API 无法更改或移动 Google Workspace 账号的主域名。不过，该 API 可以重命名用户账号，将其邮箱从一个网域更改为另一个网域。
    • 对于 Google Workspace 账号，您有 21 天的时间来验证您对主域名的所有权。对于附加域名，您必须先验证域名所有权，然后才能将该域名用作用户的主邮箱。在这些情况下，21 天的宽限期不适用。
    • 在此版本的 API 中，主网域的设置适用于与该账号关联的所有网域，但用户对 Google Workspace 服务的访问权限除外。
  • 其他账号域名 - 建立主域名并设置账号后，您可以将其他域名添加到账号中。对于其他域名，请在设置该域名时以及将该域名用作用户的主邮箱之前，验证您的所有权。
  • 用户的主网域 - 用户主邮箱中使用的网域即为用户的主网域。此域名可以是账号中的任何域名，包括主域名。
如需了解最新的多网域限制，请参阅多网域限制。这包括网域别名、账号合并等信息。
警告、群组成员 GROUP_CANNOT_CONTAIN_CYCLE – API 不允许群组成员资格中存在循环。例如，如果群组 1 是群组 2 的成员，则群组 2 不能是群组 1 的成员。