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

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

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

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

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

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

Категории ограничений API	Ограничения
Создание пользователей	С помощью Directory API можно создавать не более 10 пользователей в секунду на домен.
Удаление пользователей	С помощью Directory API можно удалять до пяти пользователей в секунду в одном домене. Это ограничение для бэкенд-службы на домен, которое нельзя изменить в квотах проекта в консоли Google Cloud. При отправке пакетных запросов убедитесь, что общее количество операций во всех пакетах не превышает 5 запросов в секунду.
Удаление участников группы	С помощью Directory API можно удалять до 30 участников группы в секунду в каждом домене. Это ограничение для бэкенд-службы на уровне домена, которое нельзя изменить в квотах проекта в консоли Google Cloud. При отправке пакетных запросов убедитесь, что общее количество операций во всех пакетах не превышает 30 запросов в секунду.
Группа добавлена в качестве участника в другую группу	Участники дочерней группы могут появиться в списке участников родительской группы с задержкой до 10 минут. Это ограничение может меняться в зависимости от емкости системы.
Мобильные устройства	С помощью Directory API можно выполнять: 20 запросов действий в секунду. 20 запросов на удаление в секунду. 10 GET-запросов в секунду. 10 запросов на получение списка в секунду.
Переименование аккаунтов пользователей	Изменения вступят в силу во всех сервисах в течение 10 минут. Перед переименованием пользователя рекомендуется выйти из всех сеансов браузера и сервисов. Подробнее об обновлении пользователей…
Создание и обновление организационных подразделений	С помощью Directory API можно создавать или обновлять не более одного организационного подразделения в секунду для каждого клиента. Иерархия организационных подразделений клиента ограничена 35 уровнями. Общее количество организационных подразделений у одного клиента не должно превышать 40 000.
Категории квот API	Квоты
Устройства Chrome annotatedLocation, максимальное количество символов	Максимальное количество символов для геоданных устройства – 200.
Устройства Chrome notes, максимальное количество символов	Максимальное количество символов в примечании – 500.
Устройства Chrome, не более user символов	Максимальное количество символов в имени пользователя устройства – 100.
Максимальное количество псевдонимов домена	Максимальное количество псевдонимов домена – 20.
Группы, описание	Максимальное количество символов в описании – 4096.
Группы (на аккаунт)	В устаревшей бесплатной версии 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. Чтобы изменить адрес электронной почты участника группы, используйте консоль администратора Google. После этого API автоматически отразит изменения адреса электронной почты.
Группы, настройки	Настройки доступа, параметры совместного использования, мониторинг и архив обсуждений в Группах управляются с помощью консоли администратора Google. Дополнительную информацию о настройках групп можно найти в Справочном центре для администраторов.
Группы, отправка сообщений	Чтобы предотвратить распространение спама и злоупотребление электронной почтой, Google ограничивает количество сообщений, которые можно отправить внешним получателям за один раз. Если вы отправляете сообщение группе, каждый внешний участник считается одним получателем. Дополнительную информацию можно найти в статьях Ограничения на отправку почты и Как предотвратить блокировку почты, предназначенной пользователям Gmail, или ее отправку в папку "Спам".
Группы, отправка отчетов о недоставке	Нельзя отправлять и пересылать отчеты о недоставленных сообщениях.
Ограничения для групп, созданных пользователями	Ограничения для групп, созданных пользователями, приведены в Справочном центре для администраторов.
Организационное подразделение, включение и отключение сервисов	Включать и отключать сервисы для организационного подразделения можно в консоли администратора Google.
Пароли	Может содержать любую комбинацию символов. Минимальное количество символов – 8. Максимальная длина – 100 символов.
Фото	В этой версии API фотография – это последнее фото профиля Google пользователя.
Имена пользователей	Имена пользователей могут содержать буквы (a–z), цифры (0–9), дефисы (-), символы подчеркивания (_) и точки (.). В 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.