Как управлять квотой для Google Analytics Data API

Минхаз Кази (Minhaz Kazi), специалист по связям с разработчиками, Google Аналитика, февраль 2023 г.

Если вы разрабатываете приложения с помощью Google Analytics Data API, вам необходимо знать его квоты и ограничения. В хорошо продуманных приложениях меньше шансов того, что пользователи превысят квоты. Применив некоторые рекомендации, вы также можете повысить эффективность запросов к API. Благодаря этому отчеты и сводки в вашем приложении будут создаваться быстрее и пользователям станет удобнее работать с ним. В этой статье рассказывается о системе квот и приводятся рекомендации по работе с Google Analytics Data API.

Система квот для Google Analytics Data API

Поскольку с Google Аналитикой работают миллионы разработчиков и пользователей, квота на запросы к API защищает систему от обработки слишком большого количества данных и обеспечивает равномерное распределение системных ресурсов. В Data API управление квотами API для ресурсов Google Аналитики 4 осуществляется с помощью системы сегмента токенов. Чтобы понять, как она работает, представьте себе контейнер (сегмент), в котором находится ограниченное количество токенов. Каждый запрос к API сначала проверяет, есть ли в сегменте свободный токен. Если токенов не осталось, запрос не выполняется. Если токены есть, запрос выполняется и потребляет один или больше токенов в зависимости от сложности запроса. Через определенные промежутки времени сегмент вновь заполняется токенами.

В зависимости от того, какой метод Data API, вы используете, есть три отдельных категории квот:

Отчет в реальном времени (для runRealtimeReport).
Последовательность (для runFunnelReport).
Основное (для всех других методов).

Методы Data API проверяют наличие токенов квоты в следующих сегментах:

На один ресурс в день.
На один ресурс в час.
На один проект в одном ресурсе в час.
Одновременных запросов на ресурс.
Серверных ошибок на один проект в одном ресурсе в час.

Эти пять сегментов проверяются каждый раз, когда к Data API поступает запрос для ресурса. Если хотя бы один из этих сегментов пустой, запрос не будет выполнен и сразу же появится сообщение об ошибке 429. Если пустых сегментов нет, будет потреблен один токен из сегмента Одновременных запросов на ресурс и запрос к API будет выполнен. В зависимости от сложности запроса после его выполнения будет потреблено определенное количество токенов из первых трех сегментов в списке выше. При этом в сегмент Одновременных запросов на ресурс будет возвращен один токен.

Квота На один проект в одном ресурсе в час помогает гарантировать, что исчерпание квоты для одного или нескольких пользователей не повлияет на других пользователей приложения. Проект в этом случае означает проект GCP вашего приложения. Квота На один ресурс в час обычно в четыре раза больше квоты На один проект в одном ресурсе в час. Для конечных пользователей это означает, что для исчерпания квоты На один ресурс в час к ресурсу должны обратиться хотя бы четыре разных проекта. Применение квоты на уровне проекта и ресурса гарантирует, что превышение лимита ограничено одним ресурсом и не повлияет на другие ресурсы, которые использует ваше приложение.

Квота на количество серверных ошибок касается ответов API с кодами 500 и 503. Если во время доступа приложения к ресурсу возникает слишком много ошибок, квота Серверных ошибок на один проект в одном ресурсе в час будет исчерпана.

Все сегменты квоты заполняются токенами до максимума через заданные интервалы. Актуальную информацию можно найти в разделе Квоты Google Analytics Data API. Например, для методов из категории Основное выделяется 1250 токенов квоты в сегменте На один проект в одном ресурсе в час. Предположим, запрос от вашего приложения в среднем потребляет 10 токенов квоты. В таком случае ваше приложение сможет выполнить 125 запросов из категории "Основное" в час для стандартного ресурса и в 10 раз больше (1250 запросов из категории Основное) для любого ресурса Аналитики 360. Более высокий лимит на количество токенов квоты – это одно из основных преимуществ ресурсов Аналитики 360.

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

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

Таким образом, один и тот же запрос при обращении к разным ресурсам может потреблять разное количество токенов, так как количество уникальных значений в параметрах или объем трафика могут различаться. Однако, для ресурсов со схожими уровнями трафика или конфигурацией можно ожидать приблизительно одинакового потребления. На основе этого можно прогнозировать количество потребляемых клиентом токенов на этапе планирования и разработки приложения.

Как отслеживать использование квоты

Чтобы отслеживать использование квоты и передавать эту информацию конечному пользователю, можно добавить в тело запроса к API следующий параметр: "returnPropertyQuota": true. В результате вместе с ответом API будет возвращаться объект PropertyQuota. В объекте PropertyQuota будут содержаться сведения о количестве потребленных токенов и оставшейся квоте для всех пяти сегментов. Ниже приведен пример текста запроса и ответа.

Запрос

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Ответ

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

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

Управление квотами

Чтобы вы могли использовать Data API максимально эффективно, рекомендуем следовать приведенным ниже советам. Кроме того, чтобы работать с большим количеством данных через API, можно перейти на ресурсы Аналитики 360.

Как сделать приложение более удобным и отвечающим ожиданиям пользователей

Показывайте пользователям предупреждение перед запуском запросов, которые могут потреблять много токенов, например запросов, содержащих много параметров с большим количеством уникальных значений или широкий временной диапазон. Это поможет пользователям избежать ненужных изменений в отчетах и ограничить запрос только необходимыми данными.
В специальных отчетах добавьте возможность видеть, как каждый элемент отчета использует запрос. Например, вы можете реализовать окно отладки с данными о количестве потребленных токенов для каждого элемента отчета.
Добавьте информационные сообщения с описанием типа ошибки потребления квоты и дальнейших шагов пользователя.
Перейдите на ресурсы Google Аналитики 360, так как их лимиты использования квоты в 5–10 раз выше, чем у стандартных.

В Google Аналитике 4 нельзя увеличить заданные по умолчанию лимиты квоты на запросы к Data API. В Аналитике 360 для ресурсов Google Аналитики 4 лимиты квоты увеличены. Если пользователи превышают лимиты квоты даже после того, как вы применили наши рекомендации, им следует перейти на Аналитику 360. Другой вариант – экспорт данных Google Аналитики на уровне события в BigQuery. Это позволит пользователям самостоятельно анализировать данные.

Если у вас есть дополнительные вопросы о квотах Data API, присоединитесь к группе Google Аналитики в Discord или задайте их на сайте Stack Overflow. Если вас интересует расширение функций Data API, вы можете опубликовать свои предложения в нашей системе отслеживания ошибок.