API Google Календаря имеет квоты, обеспечивающие справедливое использование всеми пользователями. При использовании API Календаря следует учитывать три важных ограничения:
Квоты на использование API : применяются к каждому проекту и каждому пользователю. Для получения дополнительной информации см. Типы квот на использование API календаря .
Общие ограничения на использование Google Календаря : API Google Календаря — это общедоступный сервис, который имеет ограничения, призванные защитить общую производительность системы Google Workspace. Для получения дополнительной информации см. раздел «Как избежать ограничений на использование Календаря».
Эксплуатационные ограничения : Эти ограничения могут быть сняты в любой момент. Например, если вы попытаетесь записать данные в один и тот же календарь с небольшим интервалом.
Квоты API календаря
Вводятся два типа квот:
В минуту на проект: это количество запросов, которые ваш проект Google Cloud может выполнить за одну минуту.
В минуту на пользователя на проект: это количество запросов, которые может отправить один конкретный пользователь в вашем облачном проекте. Это ограничение призвано помочь вам обеспечить справедливое распределение использования между вашими пользователями.
Квоты рассчитываются поминутно с использованием скользящего окна. Резкий всплеск трафика, превышающий вашу поминутную квоту в течение одной минуты, приведет к ограничению скорости в следующем окне, чтобы гарантировать, что в среднем ваше использование останется в пределах квот.
В следующей таблице подробно указаны эти ограничения:
| Тип ограничения использования | Лимит |
|---|---|
| Поминутно на проект | 10 000 запросов |
| Поминутная оплата за пользователя за проект | 600 запросов |
Порог ежедневного выставления счетов
Этот лимит на один проект в день определяет максимальное количество запросов, которые ваш проект Google Cloud может использовать в течение 24 часов до начала начисления платы.
Использование сервиса ниже этого порога не влечет за собой дополнительных расходов, и с вашего аккаунта Google Cloud не взимается плата. Полная информация о выставлении счетов будет предоставлена позже в 2026 году, при этом изменения вступят в силу не менее чем за 90 дней.
Вы не можете запросить увеличение этого суточного лимита.
В следующей таблице подробно указаны ограничения:
| Тип порогового значения | Лимит |
|---|---|
| За день на проект | 1 000 000 запросов |
Для получения дополнительной информации см. стандартизированную модель Google Workspace для инструментов и API агентов .
Устранение ошибок, связанных с временными квотами.
Для всех ошибок, связанных со временем (максимум N запросов за X минут), мы рекомендуем, чтобы ваш код перехватывал исключение и использовал усеченную экспоненциальную задержку , чтобы ваши устройства не создавали чрезмерную нагрузку.
Экспоненциальная задержка — это стандартная стратегия обработки ошибок в сетевых приложениях. Алгоритм экспоненциальной задержки повторяет запросы, используя экспоненциально увеличивающиеся промежутки времени ожидания между запросами, вплоть до максимального времени задержки. Если запросы по-прежнему не удаются, важно, чтобы задержки между запросами увеличивались со временем, пока запрос не будет успешно выполнен.
Пример алгоритма
Алгоритм экспоненциальной задержки повторяет запросы в экспоненциальном порядке, увеличивая время ожидания между повторными попытками до максимального значения задержки. Например:
- Отправьте запрос к API Google Календаря.
- Если запрос не удался, подождите 1 +
random_number_millisecondsи повторите запрос. - Если запрос не удался, подождите 2 +
random_number_millisecondsи повторите запрос. - Если запрос не удался, подождите 4 +
random_number_millisecondsи повторите запрос. - И так далее, вплоть до
maximum_backoffвремени задержки. - Продолжайте ждать и повторять попытки до определенного максимального количества раз, но не увеличивайте интервал ожидания между повторными попытками.
где:
- Время ожидания составляет
min(((2^n)+random_number_milliseconds), maximum_backoff), при этомnувеличивается на 1 для каждой итерации (запроса). -
random_number_milliseconds— это случайное число миллисекунд, меньшее или равное 1000. Это помогает избежать ситуаций, когда множество клиентов синхронизированы из-за какой-либо ситуации и все они одновременно повторяют запрос, отправляя его синхронизированными волнами. Значениеrandom_number_millisecondsпересчитывается после каждого повторного запроса. -
maximum_backoffобычно составляет 32 или 64 секунды. Подходящее значение зависит от конкретного случая использования.
Клиент может продолжать попытки после достижения значения maximum_backoff time. После этого значения увеличение backoff time не требуется. Например, если клиент использует значение maximum_backoff time равное 64 секундам, то после достижения этого значения он может повторять попытки каждые 64 секунды. В какой-то момент клиентам следует запретить бесконечные повторные попытки.
Время ожидания между повторными попытками и количество повторных попыток зависят от сценария использования и условий сети.
Цены
Все стандартные функции API Google Calendar доступны без дополнительной платы. Превышение лимитов запросов, установленных квотой, по плану повлечет за собой списание средств с вашего платежного аккаунта Google Cloud позднее в 2026 году. Для получения дополнительной информации см. стандартизированную модель Google Workspace для инструментов и API агентов .
Запросить увеличение квоты
В зависимости от объема используемых ресурсов вашего проекта, вам может потребоваться запросить корректировку квоты. Вызовы API, выполняемые сервисным аккаунтом, считаются использованием одного аккаунта. Подача заявки на корректировку квоты не гарантирует ее одобрения. Запросы на корректировку квоты, которые значительно увеличат ее значение, могут обрабатываться дольше.
Не все проекты имеют одинаковые квоты. По мере того, как вы будете все больше использовать Google Cloud, значения ваших квот могут потребовать увеличения. Если вы ожидаете значительного увеличения использования в будущем, вы можете заблаговременно запросить корректировку квот на странице «Квоты и системные ограничения» в консоли Google Cloud.
Для получения более подробной информации ознакомьтесь со следующими ресурсами:
Устранение неполадок
Если превышена любая из квот, вы будете ограничены по скорости передачи данных и получите код состояния 403 usageLimits или 429 usageLimits в ответ на ваши запросы.
Если это произойдёт, вы можете попробовать следующее:
Обязательно соблюдайте все рекомендации: используйте экспоненциальную задержку , рандомизируйте шаблоны трафика и используйте push-уведомления .
Если ваш проект развивается и у вас появляется больше пользователей, вы можете запросить увеличение квоты .
Если вы достигли лимита квоты на пользователя, вы можете сделать следующее:
Если вы используете служебный аккаунт, распределите нагрузку между пользователями или разделите ее между несколькими служебными аккаунтами.
Хотя вы можете запросить увеличение квоты на пользователя, в целом не рекомендуется увеличивать ее выше значения по умолчанию, поскольку ваше приложение может начать сталкиваться с другими типами ограничений, например, с ограничениями на использование общего календаря или операционными ограничениями.
Проверьте свои квотные лимиты, зарегистрировав отдельный тестовый проект с аналогичной конфигурацией, как у вашего производственного проекта. Для получения дополнительной информации см. раздел «Проверка обработки квотных лимитов» .
Рандомизация транспортных потоков
Клиенты календаря подвержены резким скачкам трафика, вызванным одновременным выполнением операций несколькими клиентами. Например, распространенной нежелательной практикой для клиента календаря является выполнение полной синхронизации в полночь. Это почти наверняка приведет к превышению поминутной квоты и вызовет ограничение скорости и задержки.
Чтобы этого избежать, по возможности распределяйте трафик в течение дня. Если вашему клиенту требуется ежедневная синхронизация, пусть он сам выбирает случайное время (разное для каждого клиента). Если же операция выполняется регулярно, изменяйте интервал на +/- 25%. Это позволит более равномерно распределить трафик и значительно улучшить пользовательский опыт.
Используйте push-уведомления
Распространенный сценарий использования — выполнение действия всякий раз, когда что-то меняется в календаре пользователя. Антипаттерн в этом случае — многократный опрос всех интересующих календарей. Это очень быстро исчерпает всю вашу квоту. Например, если ваше приложение обслуживает 5000 пользователей и опрашивает календарь каждого пользователя раз в минуту, то для этого потребуется квота не менее 5000 опросов в минуту, даже до начала выполнения какой-либо работы.
Приложения на стороне сервера могут регистрироваться для получения push-уведомлений, что позволяет нам сообщать вам о важных событиях. Настройка таких уведомлений требует больше усилий, но позволяет значительно эффективнее использовать вашу квоту и улучшает пользовательский опыт. Обязательно укажите eventType , о котором вы хотите получать уведомления. Для получения дополнительной информации см. раздел «Push-уведомления» .
Правильное распределение средств с использованием сервисных счетов.
Если ваше приложение выполняет запросы с использованием делегирования на уровне домена , по умолчанию плата взимается с учетной записи службы в соответствии с квотами «за минуту на пользователя на проект», а не с пользователя, от имени которого вы от имени работаете. Это означает, что у учетной записи службы, скорее всего, закончится квота, и она будет ограничена по количеству запросов, даже если она работает с календарями нескольких пользователей.
Этого можно избежать, используя параметр URL quotaUser (или заголовок HTTP x-goog-quota-user ), чтобы указать, с какого пользователя взимается плата. Он используется только для расчета квоты. Для получения дополнительной информации см. раздел «Ограничение запросов на пользователя» .
Обработка лимитов квот тестирования
Чтобы убедиться, что ваше приложение сможет корректно обрабатывать достижение лимитов квот на практике (например, с помощью повторных попыток с экспоненциальной задержкой ) и свести к минимуму любые потенциальные неудобства для пользователей, мы настоятельно рекомендуем протестировать ваш сценарий в реальной среде.
Для тестирования без вмешательства в реальное использование вашего приложения мы рекомендуем зарегистрировать отдельный тестовый проект в консоли Google Cloud и настроить экран согласия OAuth аналогично вашему рабочему проекту. Затем вы можете установить искусственно заниженные лимиты квот для этого проекта и наблюдать за поведением вашего приложения.