API Google Календаря имеет квоты, обеспечивающие справедливое использование ресурсов всеми пользователями. При использовании API Календаря следует учитывать три важных ограничения:
- Квоты на использование API устанавливаются для каждого проекта и пользователя. Подробнее см. в следующем разделе.
- Общие ограничения на использование Календаря : избегайте ограничений на использование Календаря .
- Операционные ограничения: скорость может быть ограничена в любой момент. Например, если вы попытаетесь быстро записать что-то в один и тот же календарь.
Типы квот на использование 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 Календаря бесплатно. Превышение квоты запросов не влечет за собой дополнительных расходов, и с вашего счета не будет взиматься плата.