API каталога: ограничения и квоты

Ограничения и квоты защищают инфраструктуру Google от автоматизированных процессов, использующих Directory API ненадлежащим образом. Чрезмерные запросы от API могут быть результатом безобидной опечатки или неэффективно спроектированной системы, которая выполняет ненужные вызовы API. Независимо от причины, блокировка трафика из определенного источника после достижения им определенного уровня необходима для общего состояния системы Google Workspace. Это гарантирует, что действия одного разработчика не смогут негативно повлиять на более широкое сообщество.

В том маловероятном случае, если ваш запрос API не удался, API возвращает код состояния HTTP и причину ошибки. Кроме того, тело ответа содержит подробное описание причины ошибки.

В следующем списке показаны возможные коды ошибок, причины, соответствующие описания и рекомендуемые действия для ошибок, вызванных превышением ограничений квоты.

Код Причина Описание Рекомендованное действие
403 userRateLimitExceeded Указывает, что лимит скорости пользователя превышен. Значение по умолчанию, установленное в консоли Google Cloud, составляет 2400 запросов в минуту на пользователя для каждого проекта Google Cloud. Увеличьте ограничения на пользователя на странице «Квоты Admin SDK API» вашего проекта Google Cloud или замедлите скорость отправки запросов с помощью экспоненциальной задержки .
403 квота превышена Указывает, что достигнут предел одновременных запросов для определенной операции. Повторите попытку, используя экспоненциальную задержку . Вам необходимо замедлить скорость отправки запросов.
429 ограничение скорости превышено Указывает, что достигнут предел одновременных запросов для определенной операции. Повторите попытку, используя экспоненциальную задержку . Вы должны замедлить скорость отправки запросов. Это ограничение действует для каждой учетной записи 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 Пределы
Создание пользователей Вы не можете создавать более 10 пользователей на домен в секунду с помощью API каталога.
Группа добавлена ​​в качестве участника в другую группу Возможна задержка до 10 минут, прежде чем участники дочерней группы станут членами родительской группы. Этот предел может меняться в зависимости от мощности системы.
Мобильные устройства

Используя API каталога, вы можете выполнить до:

  • 20 запросов действий в секунду.
  • 20 запросов на удаление в секунду.
  • 10 запросов на получение в секунду.
  • 10 запросов к списку в секунду.
Переименование пользователей Распространение по всем сервисам может занять до 10 минут. Перед переименованием пользователя рекомендуется выйти из всех сеансов и сервисов браузера. Дополнительные сведения см. в разделе Обновление пользователей .
Создание/обновление организационных подразделений
  • Вы не можете создавать/обновлять более 1 организационного подразделения для каждого клиента в секунду с помощью API каталога.
  • Иерархия организационных подразделений клиента ограничена 35 уровнями глубины.
  • Общее количество организационных единиц на одного клиента не должно превышать 40 000.
Категории квот API Квоты
Устройства Chrome annotatedLocation , максимальное количество символов Максимальное количество символов для информации о местоположении устройства — 200.
notes к устройствам Chrome, максимальное количество символов Максимальное количество символов в заметках устройства — 500.
Устройства Chrome, максимальное количество символов user Максимальное количество символов в имени пользователя устройства — 100.
Псевдонимы домена, максимум Максимальное количество псевдонимов домена — 20.
Группы, описание Максимальное количество символов в описании — 4096.
Группы, на аккаунт В учетной записи G Suite Legacy Free Edition количество групп ограничено 10. В других версиях количество групп не ограничено.
Группы, участников в группе С учетной записью G Suite Legacy Free Edition группа может содержать до 100 участников. В других редакциях нет ограничений на количество участников в группе. Ограничения на членство в группах для каждого пользователя см. в разделе Общие сведения о политиках и ограничениях групп.
строка запроса maxResults API возвращает:
  • Chrome и мобильные устройства — значение по умолчанию и максимум 100 записей на странице.
  • Группы и члены групп — по умолчанию и максимум 200 записей на странице.
  • Пользователи — по умолчанию 100 записей и максимум 500 записей на странице.
Псевдоним пользователя и ресурсы организационного подразделения не используют разбиение на страницы ответа. Все основные электронные письма пользователей возвращаются в алфавитном порядке, а порядок ответов не чувствителен к регистру.
Несколько доменов, максимальное количество доменов, разрешенное в учетной записи 600 (1 основной домен + 599 дополнительных доменов)
Организационная единица, максимальное количество пользователей, перемещаемых одновременно Одновременно можно переместить 20 пользователей. И основные адреса электронной почты пользователя уже должны существовать в учетной записи.
Псевдонимы пользователей Общее количество псевдонимов, разрешенных для каждой учетной записи пользователя, составляет 30.
Псевдонимы пользователей с использованием удаленного псевдонима Удаленный псевдоним пользователя можно немедленно использовать снова.

Другие типы лимитов Ограничения и рекомендации
Биллинг и создание пользователей Для пользователей гибкого плана Google Workspace создание пользователей с использованием этого API будет иметь финансовые последствия и приведет к списанию средств с вашего платежного аккаунта клиента. Например, если у вас гибкий план Google Workspace, создание 10 пользователей приведет к тому, что в вашей учетной записи будет размещена плата за 10 лицензий Google Workspace, пропорциональная с момента создания. Если у вас годовой план, вы уже обязались заранее заплатить за определенное количество лицензий и можете создать столько пользователей, сколько указано в ваших обязательствах. Дополнительную информацию о планах выставления счетов и вашем платежном аккаунте см. в справочном центре администрирования .
Имя и Фамилия Имя и фамилия могут содержать не более 40 символов. Они поддерживают символы Юникода/UTF-8 и могут содержать пробелы, буквы (az), цифры (0–9), тире (-), косую черту (/) и точки (.). Дополнительную информацию о правилах использования символов смотрите в справочном центре администрирования .
Группы, удаление Удаление группы не приводит к удалению учетных записей пользователей участников группы.
Группы и участники групп, смена адреса электронной почты В этой версии API адрес электронной почты группы можно изменить до включения службы Google Workspace. Используйте консоль администратора , чтобы изменить адрес электронной почты участника группы. После изменения API автоматически отражает изменения адреса электронной почты.
Группы, настройки Настройки доступа к группам, параметры общего доступа, мониторинг и архив обсуждений управляются с помощью консоли администратора. Дополнительную информацию о настройках групп смотрите в справочном центре администрирования .
Группы, отправка сообщений Чтобы предотвратить спам и злоупотребления электронной почтой, Google ограничивает количество сообщений, которые вы можете отправить одновременно внешним получателям. Если вы отправляете сообщение группе, каждый внешний участник считается одним получателем. Дополнительную информацию см. в разделах «Ограничения на отправку электронной почты» и «Предотвращение блокировки или отправки почты пользователям Gmail в спам» .
Группы, отправляющие сообщения NDR Вы не можете отправлять или пересылать уведомления о недоставке (NDR), также называемые «сообщениями о недоставке», группе.
Группы, созданные пользователями, ограничения Ограничения групп, созданных пользователями, см. в Справочном центре администрирования.
Организационное подразделение, включение/отключение услуг Используйте консоль администратора, чтобы управлять включением и отключением служб для организационного подразделения.
Пароли Может содержать любую комбинацию символов. Требуется минимум 8 символов. Максимальная длина — 100 символов.
Фото В этой версии API фотография — это последняя фотография пользователя в профиле Google.
Имена пользователей Имена пользователей могут содержать буквы (az), цифры (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 не допускает циклическое членство в группах. Например, если группа1 является членом группы2, группа2 не может быть членом группы1.