API Google Календаря имеет квоты, обеспечивающие справедливое использование всеми пользователями. При использовании API Календаря следует учитывать три важных ограничения:
- Для каждого проекта и каждого пользователя действуют квоты на использование API . Подробнее см. следующий раздел.
- Общие ограничения на использование календаря : Избегайте ограничений на использование календаря .
- Ограничения на скорость выполнения операций: в любой момент может быть установлено ограничение на количество операций. Например, если вы попытаетесь записать данные в один и тот же календарь с небольшим интервалом.
Типы квот на использование Calendar API
Вводятся два типа квот:
- В минуту на проект: это количество запросов, выполняемых вашим проектом в Google Cloud.
- В минуту на проект на пользователя: это количество запросов, сделанных любым конкретным пользователем в вашем облачном проекте. Это ограничение призвано помочь вам обеспечить справедливое распределение использования между вашими пользователями.
Квоты рассчитываются поминутно с использованием скользящего окна, поэтому резкий всплеск трафика, превышающий вашу поминутную квоту в течение одной минуты, приведет к ограничению скорости в следующем окне, чтобы гарантировать, что в среднем ваше использование останется в пределах квот.
Если превышена любая из квот, ваши запросы будут ограничены по количеству запросов, и вы получите код состояния 403 usageLimits или 429 usageLimits . В этом случае вы можете сделать следующее:
- Обязательно соблюдайте все рекомендации: используйте экспоненциальную задержку , рандомизируйте шаблоны трафика , используйте push-уведомления .
- Если ваш проект развивается и у вас появляется больше пользователей, вы можете запросить увеличение квоты на проект .
- Если достигнут лимит квоты на пользователя, вы можете сделать следующее:
- Если вы используете служебный аккаунт, распределите нагрузку между пользователями или разделите ее между несколькими служебными аккаунтами.
- Хотя вы можете запросить увеличение квоты на пользователя, в целом не рекомендуется увеличивать ее выше значения по умолчанию, поскольку ваше приложение может начать сталкиваться с другими типами ограничений, например, с ограничениями на использование календаря или операционными ограничениями.
Запрос на увеличение квоты
Чтобы просмотреть или изменить лимиты использования для вашего проекта, или запросить увеличение квоты, выполните следующие действия:
- Если у вас еще нет платежного аккаунта для вашего проекта, создайте его.
- Перейдите на страницу «Включенные API» в библиотеке API в консоли API и выберите API из списка.
- Чтобы просмотреть и изменить настройки, связанные с квотами, выберите «Квоты» . Чтобы просмотреть статистику использования, выберите «Использование» .
Используйте экспоненциальную задержку
Если мы попросим вас замедлить скорость запросов, мы вернем ответ 403 "usageLimits" или 429 (см. полную документацию по ошибкам ). Это не критическая ошибка, и мы ожидаем, что вы повторите запрос через короткий промежуток времени. Если запросы по-прежнему поступают слишком быстро, мы отправим запрос снова, и так далее. Для корректной работы важно, чтобы задержки между запросами со временем увеличивались.
Как правило, следует использовать усеченную экспоненциальную задержку ; в документации Cloud Storage хорошо объясняется, как это работает и какой алгоритм предпочтительнее. Если вы используете клиентскую библиотеку Google, это обычно будет сделано автоматически; обратитесь к документации вашей библиотеки. Обычно следует использовать реализацию библиотеки, а не писать свою собственную.
Рандомизация транспортных потоков
Клиенты календаря подвержены резким скачкам трафика, вызванным одновременным выполнением операций несколькими клиентами. Например, распространенной нежелательной практикой для клиента календаря является выполнение полной синхронизации в полночь. Это почти наверняка приведет к превышению поминутной квоты и, как следствие, к ограничению скорости и задержкам.
Чтобы этого избежать, по возможности распределяйте трафик в течение дня. Если вашему клиенту требуется ежедневная синхронизация, пусть он сам выбирает случайное время (разное для каждого клиента). Если же операция выполняется регулярно, изменяйте интервал на +/- 25%. Это позволит более равномерно распределить трафик и значительно улучшить пользовательский опыт.
Используйте push-уведомления
Распространенный сценарий использования — необходимость выполнения действия при каждом изменении в календаре пользователя. Антипаттерн в этом случае — многократный опрос всех интересующих календарей. Это очень быстро исчерпает всю квоту — например, если в вашем приложении 5000 пользователей и вы опрашиваете календарь каждого пользователя раз в минуту, то вам потребуется квота как минимум в 5000 запросов в минуту еще до начала выполнения какой-либо работы.
Приложения на стороне сервера могут регистрироваться для получения push-уведомлений, что позволяет нам сообщать вам о важных событиях. Настройка таких уведомлений требует больше усилий, но позволяет значительно эффективнее использовать вашу квоту и улучшает пользовательский опыт. Обязательно укажите eventType , о котором вы хотите получать уведомления. Для получения дополнительной информации см. раздел «Push-уведомления» .
Надлежащий бухгалтерский учет с использованием счетов обслуживания.
Если ваше приложение выполняет запросы с использованием делегирования на уровне домена , по умолчанию плата взимается с учетной записи службы в соответствии с квотами «за минуту на проект на пользователя», а не с пользователя, которого вы имитируете. Это означает, что у учетной записи службы, скорее всего, закончится квота, и она будет ограничена по количеству запросов, даже если она работает с календарями нескольких пользователей. Вы можете избежать этого, используя параметр URL-адреса quotaUser (или заголовок HTTP x-goog-quota-user ), чтобы указать, с какого пользователя будет взиматься плата. Это используется только для расчета квоты. Дополнительную информацию см. в разделе «Ограничение запросов на пользователя» в документации Cloud.
Обработка лимитов квот тестирования
Чтобы гарантировать корректную обработку достижения лимитов квот вашим приложением на практике (например, путем повторных попыток с экспоненциальной задержкой ) и минимизировать любые потенциальные неудобства для пользователей, мы настоятельно рекомендуем протестировать этот сценарий в реальных условиях.
Чтобы подобное тестирование не мешало реальному использованию вашего приложения, мы рекомендуем зарегистрировать отдельный тестовый проект в Google API Console и настроить его аналогично вашему рабочему проекту. Затем вы можете установить искусственно заниженные квоты для этого проекта и наблюдать за поведением вашего приложения.
Цены
Использование API Google Календаря предоставляется бесплатно. Превышение лимитов запросов не влечет за собой дополнительных расходов, и с вашего счета не взимается плата.