Ограничения и квоты Data API

Для Data API действуют следующие ограничения и квоты.

Как применяются квоты

Для всех запросов к Google Analytics Data API v1 требуется проект Google Cloud, и на них распространяются квоты, описанные на этой странице. Квоты расходуются независимо от метода, используемого для идентификации вызывающего проекта, в том числе:

• Запросы, аутентифицированные с помощью учетных данных OAuth 2.0.
• Запросы, для аутентификации которых используется только ключ API.

Ключи API используются для связывания запроса с определенным проектом Google Cloud в целях квотирования и выставления счетов. Все вызовы API, выполненные с использованием учетных данных или ключа API из вашего проекта, будут учитываться в применимых квотах проекта и ресурса Google Аналитики.

Категории квот

В Data API есть четыре категории квот на запросы: "Основные", "В реальном времени", "Воронка" и "Чат".

Запросы к API, в которых используются основные методы, расходуют основные квоты. Запросы к методам Realtime API расходуют квоты Realtime. Запросы API к методам воронки расходуют квоты воронки. Запросы к API для методов Chat расходуют квоты Chat. Каждый запрос расходует только один тип квоты.

Квоты для ресурсов Аналитики

Все запросы расходуют квоты ресурса.

• Одновременные запросы – это запросы, которые выполняются одновременно. Чтобы снизить количество параллельных запросов, дождитесь завершения предыдущих запросов, прежде чем отправлять новые.
• Ошибки сервера – это коды 500 и 503. Квота на ошибки сервера расходуется только в том случае, если запрос приводит к ошибке сервера. Когда квота на ошибки сервера для пары "проект – ресурс" исчерпана, все запросы к ресурсу из проекта блокируются. Полный список сообщений об ошибках приведен в этой статье.
• Каждый запрос расходует квоту как для токенов на один ресурс в час, так и для токенов на один проект в одном ресурсе в час. Это означает, что к одному ресурсу должны обратиться более трех проектов, чтобы квота "Токены на один ресурс в час" была исчерпана раньше, чем квота "Токены на один проект в одном ресурсе в час".

Для ресурсов разрешено 120 потенциально пороговых запросов в час. К параметрам userAgeBracket, userGender, brandingInterest, audienceId и audienceName могут применяться пороговые значения. При показе данных о возрасте, поле и категориях интересов могут применяться пороговые значения.

Квота на токены ресурса

Токены расходуются при каждом запросе к Google Analytics Data API v1. Количество списанных токенов зависит от сложности запроса. Большинство запросов требуют не более 10 токенов, но более сложные запросы (например, запросы к Ask Advisor chat) могут потреблять больше.

Факторы, влияющие на использование токенов

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

• Количество строк. Запрос большего количества строк.
• Количество параметров и показателей. Чем больше параметров и показателей вы добавите,
• Сложность фильтра. Использование сложных выражений фильтра.
• Продолжительность диапазона дат. Запрос данных за более длительный период.
• Количество уникальных значений. Параметры с большим количеством уникальных значений (например, pagePath или специальные параметры) могут значительно увеличить стоимость токенов.
• Объем событий в ресурсе. Запросы к ресурсам с большим количеством событий могут потреблять больше токенов, чем те же запросы к ресурсам с меньшим объемом данных.

Мониторинг использования токенов

Самый эффективный способ определить стоимость токенов для ваших вызовов API – включить параметр "returnPropertyQuota": true в тело запроса (поддерживается в runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport и runFunnelReport). В ответе API будет объект PropertyQuota, в котором указано, сколько токенов было использовано для этого запроса и сколько осталось в квоте.

Пример запроса с параметром returnPropertyQuota

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

Пример полезной нагрузки ответа propertyQuota

Если задано значение "returnPropertyQuota": true, ответ включает объект propertyQuota, в котором каждое поле содержит объект QuotaStatus с целыми числами consumed и remaining:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

Каждое поле в propertyQuota соответствует квоте в квотах ресурсов Аналитики. Стоимость токенов одного запроса к API вычитается одновременно из tokensPerDay, tokensPerHour и tokensPerProjectPerHour. Если в каком-либо сегменте квоты осталось 0 токенов, последующие запросы к этому ресурсу будут возвращать ошибку 429 RESOURCE_EXHAUSTED.

Как избежать ошибок 429 RESOURCE_EXHAUSTED

• Динамически отслеживайте баланс remaining. Проверяйте propertyQuota.tokensPerProjectPerHour.remaining и propertyQuota.tokensPerHour.remaining в ответах и ограничивайте или приостанавливайте несрочные фоновые задачи, когда количество оставшихся токенов падает ниже безопасного порога.
• Пакетные запросы. Используйте batchRunReports или batchRunPivotReports, чтобы объединить до пяти отчетов в один HTTP-вызов и уменьшить издержки на передачу данных по сети (обратите внимание, что каждый отчет в пакете по-прежнему учитывается отдельно при расчете квот на токены и concurrentRequests).
• Уменьшите сложность запроса и количество элементов. Ограничьте запросы только нужными параметрами и показателями, сократите dateRanges, где это возможно, и не объединяйте несколько параметров с большим количеством элементов (например, pagePath или fullPageUrl) в часто выполняемых запросах.
• Контролируйте параллелизм запросов. Добавляйте запросы в очередь или ограничьте размер пула воркеров, чтобы количество выполняемых запросов не превышало лимит concurrentRequests (10 для Standard, 50 для Аналитики 360).
• Реализуйте экспоненциальную выдержку с ограничением количества повторных попыток. Если запрос завершается неудачно с кодом ошибки 429 RESOURCE_EXHAUSTED, 500 INTERNAL или 503 UNAVAILABLE, повторите попытку с усеченной экспоненциальной выдержкой, как описано в разделе Ответы с ошибками.

Использование и мониторинг токенов Chat

Для запросов к Ask Advisor chat токены представляют собой стоимость вычислений модели, рассуждений и извлечения базовых данных. На потребление токенов в Chat влияют:

• Запрос и аналитический охват. Сложность и широта запрошенного анализа.
• Входные и выходные токены модели. Объем обработанных контекстных данных и сгенерированного ответа.
• Токены мышления. Этапы рассуждений модели, необходимые для обобщения результатов.
• Задержка выполнения. Время, необходимое для обработки многоэтапных исследований данных.

Чтобы отслеживать использование токенов чата, задайте значение "returnPropertyQuota": true в файле ChatRequest. Ответ будет содержать объект PropertyChatQuota с полями tokensPerDay и tokensPerHour, в которых указаны использованный и оставшийся баланс.