Эта страница переведена с помощью Cloud Translation API.

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

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

Квоты на использование API : применяются к каждому проекту и каждому пользователю. Для получения дополнительной информации см. Типы квот на использование API календаря .
General Calendar usage limits : The Calendar API is a shared service that has limitations to protect the overall performance of the Google Workspace system. For more information, see Avoid Calendar use limits .
Операционные ограничения : Эти ограничения могут применяться в любое время. Например, ограничения могут применяться, если вы попытаетесь записать данные в один и тот же календарь с небольшим интервалом.

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

Вводятся два типа квот:

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

Quotas are calculated per minute using a sliding window. A rapid burst of traffic that exceeds your per-minute quota results in rate limiting during the next window to ensure that, on average, your usage remains within the quotas.

В следующей таблице подробно указаны эти ограничения:

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

Порог ежедневного выставления счетов

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

Usage under this threshold doesn't incur extra charges and your Google Cloud account isn't billed. Full billing details will be shared later in 2026 with at least 90 days' notice before any changes take effect.

Вы не можете запросить увеличение этого суточного лимита.

В следующей таблице подробно указаны ограничения:

Тип порогового значения	Лимит
За день на проект	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 секунды. В какой-то момент клиентам следует запретить бесконечные повторные попытки.

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

Цены

All standard use of the Google Calendar API is available at no additional cost. Exceeding the quota request limits is planned to incur charges to your Google Cloud billing account later in 2026. For more information, see Google Workspace standardized model for agent tools and APIs .

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

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

Не все проекты имеют одинаковые квоты. По мере того, как вы будете все больше использовать Google Cloud, значения ваших квот могут потребовать увеличения. Если вы ожидаете значительного увеличения использования в будущем, вы можете заблаговременно запросить корректировку квот на странице «Квоты и системные ограничения» в консоли Google Cloud.

Для получения более подробной информации ознакомьтесь со следующими ресурсами:

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

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

Если это произойдёт, вы можете попробовать следующее:

Обязательно соблюдайте все рекомендации: используйте экспоненциальную задержку , рандомизируйте шаблоны трафика и используйте push-уведомления .
Если ваш проект развивается и у вас появляется больше пользователей, вы можете запросить увеличение квоты .
Если вы достигли лимита квоты на пользователя, вы можете сделать следующее:
- Если вы используете служебный аккаунт, распределите нагрузку между пользователями или разделите ее между несколькими служебными аккаунтами.
- While you can request an increase in the per-user quota, in general, we don't recommend increasing it above the default value because your application might hit other types of limits, for example, general calendar usage limits or operational limits.
Проверьте свои квотные лимиты, зарегистрировав отдельный тестовый проект с аналогичной конфигурацией, как у вашего производственного проекта. Для получения дополнительной информации см. раздел «Проверка обработки квотных лимитов» .

Рандомизация транспортных потоков

Calendar clients are prone to spiky traffic patterns caused by multiple clients performing operations at the same time. For example, a common bad practice for a Calendar client is to perform a full sync at midnight. This typically exceeds your per-minute quota and causes rate limiting and backoffs.

To avoid this, spread your traffic throughout the day wherever possible. If your client needs to do a daily sync, have the client determine a random time (different for each client). If you need to perform an operation on a regular basis, vary the interval ±25%. This distributes traffic more evenly and provides a better user experience.

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

A common use case is to perform an action whenever something changes in the user's calendar. An anti-pattern here is to repeatedly poll every calendar of interest. This quickly exhausts your quota. For example, if your application has 5,000 users and polls each user's calendar once a minute, then this requires a per-minute quota of at least 5,000, even before any work is done.

Server-side applications can register for push notifications, which lets Calendar notify you when something of interest happens. These require more work to set up, but let you use quota more efficiently and provide a better user experience. Specify the eventType you want notifications for. For more information, see Push notifications .

Правильное распределение средств с использованием сервисных счетов.

If your application performs requests using domain-wide delegation , by default the service account is charged toward "per minute per user per project" quotas, and not the user you're impersonating. This means that the service account is likely to exhaust its quota and be rate limited, even though it might operate on multiple users' calendars.

You can avoid this by using the quotaUser URL parameter (or x-goog-quota-user HTTP header) to indicate which user is charged. Google uses this parameter only for quota calculations. For more information, see Limiting requests per user .

Обработка лимитов квот тестирования

To make sure that your application gracefully handles reaching quota limits in practice (for example, through retries with exponential backoff ) and to minimize any potential disturbances to your users, test your application in a realistic environment.

To test without interference to your real application usage, register a separate test-only project in the Google Cloud console and then configure the OAuth consent screen in a way similar to your production project. You can then set artificially low quota limits for this project and observe the behavior of your application.

Квоты сервера Calendar MCP

Сервер Calendar MCP использует метрику распределения стоимости запросов. В следующих таблицах подробно описана стоимость запросов для каждого метода сервера Calendar MCP по разделам:

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