Лимиты на использование

Для Google Календаря API установлены квоты, чтобы обеспечить справедливое использование всеми пользователями. При использовании Calendar API необходимо учитывать три важных ограничения:

  • Квоты на использование API. Применяются к каждому проекту и пользователю. Подробнее о типах квот на использование Calendar API…

  • Общие лимиты на использование Google Календаря. Google Calendar API – это общий сервис, в котором действуют ограничения, призванные защитить общую производительность системы Google Workspace. Подробнее о том, как избежать ограничений на использование Календаря…

  • Операционные ограничения. Могут быть изменены в любое время. Например, если вы попытаетесь быстро записать данные в один календарь.

Квоты Calendar API

Применяются два типа квот:

  • В минуту на проект. Это количество запросов, которое ваш проект Google Cloud может выполнить за одну минуту.

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

Квоты рассчитываются поминутно с использованием скользящего окна. Если в течение одной минуты трафик превысит лимит, то в течение следующей минуты частота запросов будет ограничена, чтобы среднее значение не превышало лимит.

В таблице ниже приведены подробные сведения об этих ограничениях.

Тип лимита на использование Ограничение
В минуту на проект 10 000 запросов
На пользователя в минуту на проект 600 запросов

Дневной порог оплаты

Этот лимит на день на проект определяет максимальное количество запросов, которое может использовать ваш проект Google Cloud в течение 24 часов до применения платы.

Если вы не превысите этот порог, то плата за использование не будет взиматься и средства с вашего аккаунта Google Cloud не будут списываться. Полная информация о выставлении счетов будет предоставлена позже в 2026 году не менее чем за 90 дней до вступления изменений в силу.

Запросить увеличение этого порога нельзя.

В таблице ниже приведены ограничения.

Тип порогового значения Ограничение
На проект в день 1 000 000 запросов

Дополнительную информацию можно найти в статье Стандартизированная модель Google Workspace для инструментов и API агентов.

Как устранить ошибки, связанные с временными квотами

Для всех ошибок, связанных со временем (максимум N запросов за X минут), мы рекомендуем, чтобы ваш код перехватывал исключение и использовал усеченную экспоненциальную выдержку, чтобы ваши устройства не генерировали чрезмерную нагрузку.

Экспоненциальная выдержка – это стандартная стратегия обработки ошибок для сетевых приложений. Алгоритм экспоненциальной выдержки повторяет запросы, экспоненциально увеличивая время ожидания между ними до максимального значения. Если запросы по-прежнему не выполняются, важно, чтобы задержки между ними со временем увеличивались, пока запрос не будет выполнен.

Пример алгоритма

Алгоритм экспоненциальной выдержки повторяет запросы экспоненциально, увеличивая время ожидания между повторными попытками до максимального времени выдержки. Пример:

  1. Отправьте запрос к Google Календарь API.
  2. Если запрос не удается выполнить, подождите 1 + random_number_milliseconds и повторите попытку.
  3. Если запрос не удается выполнить, подождите 2 + random_number_milliseconds и повторите попытку.
  4. Если запрос не удается выполнить, подождите 4 + random_number_milliseconds и повторите попытку.
  5. и так далее, до maximum_backoff раз.
  6. Продолжайте ждать и повторять попытки до достижения максимального количества попыток, но не увеличивайте период ожидания между попытками.

где:

  • Время ожидания составляет min(((2^n)+random_number_milliseconds), maximum_backoff), где n увеличивается на 1 для каждой итерации (запроса).
  • random_number_milliseconds – случайное число миллисекунд,не превышающее 1000. Это позволяет избежать ситуаций, когда множество клиентов синхронизируются одновременно и отправляют запросы волнами. Значение random_number_milliseconds пересчитывается после каждого повторного запроса.
  • maximum_backoff обычно составляет 32 или 64 секунды. Подходящее значение зависит от конкретного случая.

Клиент может продолжать попытки после достижения времени maximum_backoff. После этого увеличивать время задержки не нужно. Например, если клиент использует значение maximum_backoff, равное 64 секундам, то после достижения этого значения клиент может повторять попытку каждые 64 секунды. В какой-то момент клиенты должны прекратить попытки.

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

Цены

Стандартное использование Google Календаря API предоставляется бесплатно. Превышение лимитов на запросы квоты будет оплачиваться через платежный аккаунт Google Cloud. Это изменение планируется ввести в 2026 году. Дополнительную информацию можно найти в статье Стандартизированная модель Google Workspace для инструментов и API агентов.

Как запросить увеличение квоты

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

Квоты для разных проектов могут различаться. По мере того как вы будете все больше использовать Google Cloud, вам может потребоваться увеличить квоты. Если вы ожидаете значительного увеличения использования, вы можете заранее запросить корректировку квот на странице Quotas & System Limits (Квоты и системные ограничения) в консоли Google Cloud.

Дополнительную информацию можно найти в следующих ресурсах:

Устранение неполадок

Если любая из квот превышена, частота запросов ограничивается и в ответ на запросы вы получаете код статуса 403 usageLimits или 429 usageLimits.

В этом случае попробуйте сделать следующее:

  1. Следуйте всем рекомендациям: используйте экспоненциальную выдержку, рандомизируйте шаблоны трафика и используйте push-уведомления.

  2. Если ваш проект растет и у вас появляется больше пользователей, вы можете запросить увеличение квоты.

  3. Если вы достигли лимита на пользователя, вы можете:

    • Если вы используете сервисный аккаунт, распределите нагрузку между пользователями или несколькими сервисными аккаунтами.

    • Вы можете запросить увеличение квоты на пользователя, но мы не рекомендуем превышать значение по умолчанию, поскольку в этом случае приложение может столкнуться с другими ограничениями, например на использование календаря или операционными.

  4. Чтобы проверить лимиты квот, зарегистрируйте отдельный тестовый проект с конфигурацией, аналогичной конфигурации рабочего проекта. Подробнее о том, как протестировать обработку лимитов квот…

Случайные шаблоны трафика

Клиенты Календаря склонны к резким скачкам трафика, вызванным одновременным выполнением операций несколькими клиентами. Например, распространенной ошибкой для клиента Календаря является выполнение полной синхронизации в полночь. Это почти наверняка приведет к превышению квоты на минуту, ограничению частоты запросов и задержкам.

Чтобы избежать этого, по возможности распределяйте трафик в течение дня. Если клиенту требуется ежедневная синхронизация, попросите его выбрать случайное время (разное для каждого клиента). Если вам нужно регулярно выполнять какую-либо операцию, меняйте интервал на +/- 25 %. Это позволит распределить трафик более равномерно и сделать сайт удобнее для пользователей.

Используйте push-уведомления

Чаще всего это требуется, чтобы выполнить действие, когда в календаре пользователя что-то меняется. Антипаттерном в данном случае является многократный опрос каждого интересующего календаря. Это приведет к быстрому исчерпанию квоты. Например, если у вашего приложения 5000 пользователей и оно опрашивает календарь каждого пользователя раз в минуту, то для этого требуется квота не менее 5000 запросов в минуту, даже до выполнения какой-либо работы.

Серверные приложения могут регистрироваться для получения push-уведомлений, которые позволяют нам сообщать вам о важных событиях. Их сложнее настроить, но они позволяют значительно эффективнее использовать квоту и повысить удобство для пользователей. Укажите eventType, для которого вы хотите получать уведомления. Подробнее о push-уведомлениях…

Правильное распределение с сервисными аккаунтами

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

Чтобы избежать этого, используйте параметр URL quotaUser (или HTTP-заголовок x-goog-quota-user), чтобы указать произвольную строку (до 40 символов), которая уникальным образом идентифицирует каждого отдельного пользователя. Calendar API использует это значение только для расчета квот.

Чтобы использовать quotaUser для применения ограничений частоты запросов к отдельным пользователям, ваши запросы должны соответствовать следующим требованиям:

  • Добавьте ключ API с ограничением по IP-адресу. Передайте ключ API в параметре запроса key и настройте для него ограничения по IP-адресу, указав общедоступные IP-адреса ваших бэкенд-серверов. Если вы не укажете ключ API или не настроите ограничения по IP-адресам, Calendar API проигнорирует параметр quotaUser и спишет квоту с аутентифицированного аккаунта (например, сервисного).

  • Не использовать заголовок X-Goog-User-Project. Не отправлять HTTP-заголовок X-Goog-User-Project в запросах, в которых используется quotaUser. Указание пользовательского проекта переопределяет ключ API для назначения квоты, поэтому Calendar API игнорирует quotaUser.

Подробнее об ограничении количества запросов на пользователя…

Тестирование обработки лимита квоты

Чтобы убедиться, что ваше приложение может корректно обрабатывать достижение лимитов квот на практике (например, за счет повторных попыток с экспоненциальной выдержкой), и свести к минимуму любые потенциальные неудобства для пользователей, мы настоятельно рекомендуем протестировать ваш сценарий в реальной среде.

Чтобы тестирование не повлияло на работу приложения, рекомендуем зарегистрировать отдельный тестовый проект в консоли Google Cloud, а затем настроить окно запроса доступа OAuth так же, как в рабочем проекте. Затем вы можете установить искусственно заниженные лимиты квот для этого проекта и понаблюдать за поведением приложения.

Квоты MCP-сервера Календаря

MCP-сервер Календаря использует показатель распределения стоимости запросов. В таблицах ниже указана стоимость запросов для каждого метода MCP-сервера Календаря по разделам.

Квоты MCP для Календаря

Применяются два типа квот:

  • В минуту на облачный проект. Стоимость запросов к облачному проекту Google Cloud за одну минуту.

  • В минуту на пользователя на проект. Это стоимость запросов к вашему облачному проекту Google Cloud за одну минуту, которую может использовать любой конкретный пользователь.

В таблице ниже приведены сведения об этих квотах.

Тип лимита на использование Стоимость запроса
В минуту на проект 10 000
На пользователя в минуту на проект 600

Квоты на набор инструментов MCP для Календаря

В таблице ниже указана стоимость запроса для каждого набора инструментов calendarmcp.googleapis.com.

Конечная точка Инструмент Стоимость запроса

/mcp/v1

create_event

1

delete_event

10

get_event

1

list_events

1

respond_to_event

1

search_events

1

update_event

1

suggest_time

1

list_calendars

1

Дополнительную информацию можно найти в справочнике по Calendar MCP API.