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

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

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

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

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

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

  • 20 запросов на выполнение действий в секунду.
  • 20 запросов на удаление в секунду.
  • 10 запросов GET в секунду.
  • 10 запросов на получение списка в секунду.
Переименование пользователей Для распространения изменений на все сервисы может потребоваться до 10 минут. Перед переименованием пользователя рекомендуется выйти из всех сеансов браузера и сервисов, связанных с ним. Дополнительные сведения см. в разделе «Обновление пользователей» .
Создание/обновление организационных подразделений
  • С помощью API каталога невозможно создать/обновить более 1 организационной единицы на одного клиента в секунду.
  • Иерархия организационных подразделений клиента ограничена 35 уровнями.
  • Общее количество организационных единиц на одного клиента не должно превышать 40 000.
Категории квот API Квоты
Chrome devices annotatedLocation , max characters Максимальное количество символов для информации о местоположении устройства составляет 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 символов. Они поддерживают символы Unicode/UTF-8 и могут содержать пробелы, буквы (az), цифры (0-9), дефисы (-), косые черты (/) и точки (.). Для получения дополнительной информации о правилах использования символов см. справочный центр администрирования .
Группы, удаление Удаление группы не приводит к удалению учетных записей пользователей, являющихся ее членами.
Группы и участники групп, изменение адреса электронной почты В этой версии API адрес электронной почты группы можно изменить до включения службы Google Workspace. Для изменения адреса электронной почты участника группы используйте консоль администратора Google . После изменения API автоматически отобразит внесенные изменения.
Группы, настройки Настройки доступа к группам, параметры общего доступа, мониторинг и архив обсуждений управляются с помощью консоли администратора Google. Для получения дополнительной информации о настройках групп см. справочный центр администратора .
Группы, отправка сообщений Чтобы предотвратить спам и злоупотребления электронной почтой, Google ограничивает количество сообщений, которые вы можете отправить одновременно внешним получателям. Если вы отправляете сообщение группе, каждый внешний участник считается одним получателем. Для получения дополнительной информации см. разделы «Ограничения на отправку электронной почты» и «Предотвращение блокировки или попадания писем в спам для пользователей Gmail» .
Группы, отправляющие сообщения NDR Вы не можете отправлять или пересылать уведомления о недоставке (NDR), также называемые «сообщениями об ошибке доставки», в группу пользователей.
Группы, созданные пользователями, ограничения Информацию об ограничениях для групп, созданных пользователями, см. в центре справки администратора.
Организационное подразделение, включение/выключение услуг Используйте консоль администратора Google для управления включением и выключением служб для подразделения организации.
Пароли Может содержать любое сочетание символов. Минимальная длина — 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.