API Google Календаря имеет квоты, обеспечивающие справедливое использование всеми пользователями. При использовании API Календаря следует учитывать три важных ограничения:
Квоты на использование API : применяются к каждому проекту и каждому пользователю. Для получения дополнительной информации см. Типы квот на использование API календаря .
Общие ограничения на использование календаря : API календаря — это общий сервис, который имеет ограничения для защиты общей производительности системы Google Workspace. Для получения дополнительной информации см. раздел «Как избежать ограничений на использование календаря» .
Операционные ограничения : Эти ограничения могут применяться в любое время. Например, ограничения могут применяться, если вы попытаетесь записать данные в один и тот же календарь с небольшим интервалом.
Квоты API календаря
Вводятся два типа квот:
В минуту на проект: это количество запросов, которые ваш проект Google Cloud может выполнить за одну минуту.
В минуту на пользователя на проект: это количество запросов, которые может отправить один конкретный пользователь в вашем облачном проекте. Это ограничение помогает обеспечить справедливое распределение использования между вашими пользователями.
Квоты рассчитываются поминутно с использованием скользящего окна. Резкий всплеск трафика, превышающий вашу поминутную квоту, приводит к ограничению скорости в следующем окне, чтобы гарантировать, что в среднем ваше использование остается в пределах квот.
В следующей таблице подробно указаны эти ограничения:
| Тип ограничения использования | Лимит |
|---|---|
| Поминутно на проект | 10 000 запросов |
| Поминутная оплата за пользователя за проект | 600 запросов |
Порог ежедневного выставления счетов
Этот суточный лимит для каждого проекта определяет максимальное количество запросов, которые ваш облачный проект может использовать в течение 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 использует этот параметр только для расчета квоты. Для получения дополнительной информации см. раздел «Ограничение запросов на пользователя» .
Обработка лимитов квот тестирования
Чтобы убедиться, что ваше приложение корректно обрабатывает достижение лимитов квот на практике (например, с помощью повторных попыток с экспоненциальной задержкой ) и минимизирует любые потенциальные неудобства для пользователей, протестируйте приложение в реалистичной среде.
Чтобы провести тестирование без вмешательства в реальное использование вашего приложения, зарегистрируйте отдельный тестовый проект в консоли Google Cloud , а затем настройте экран согласия OAuth аналогично вашему рабочему проекту. После этого вы можете установить искусственно заниженные квоты для этого проекта и наблюдать за поведением вашего приложения.
Квоты сервера Calendar MCP
Сервер Calendar MCP использует метрику распределения стоимости запросов. В следующих таблицах подробно описана стоимость запросов для каждого метода сервера Calendar MCP по разделам:
Календарные квоты MCP
Вводятся два типа квот:
За минуту на проект: это стоимость запроса к вашему облачному проекту за одну минуту.
В минуту на пользователя на проект: это стоимость запроса, которую может понести любой отдельный пользователь в вашем облачном проекте за одну минуту.
В следующей таблице подробно указаны эти квоты:
| Тип ограничения использования | Стоимость запроса |
|---|---|
| Поминутно на проект | 10 000 |
| Поминутная оплата за пользователя за проект | 600 |
Календарь Набор инструментов MCP квоты
В следующей таблице подробно указана стоимость запросов для каждого набора инструментов calendarmcp.googleapis.com :
| Конечная точка | Инструмент | Стоимость запроса |
|---|---|---|
/mcp/v1 | | 1 |
| 10 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
Для получения более подробной информации см. справочник по API Calendar MCP .
Связанные темы
- Отправка пакетных запросов
- Повышение производительности
- Избегайте ограничений на использование календаря.