Limites e cotas da API Data

Os limites e as cotas a seguir se aplicam à API Data.

Como as cotas se aplicam

Todas as solicitações para a API Google Analytics Data v1 exigem um projeto do Google Cloud e estão sujeitas às cotas descritas nesta página. As cotas são consumidas independentemente do método usado para identificar o projeto de chamada, incluindo:

• Solicitações autenticadas com credenciais do OAuth 2.0.
• Solicitações autenticadas usando apenas uma chave de API.

As chaves de API são usadas para associar uma solicitação a um projeto na nuvem específico do Google Cloud para fins de cota e faturamento. Todas as chamadas de API feitas com credenciais ou uma chave de API do seu projeto serão contabilizadas nas cotas aplicáveis do projeto e da propriedade do Google Analytics.

Categorias de cotas

A API Data tem quatro categorias de cota de solicitação: Core, Realtime, Funnel e Chat.

As solicitações de API para métodos principais cobram cotas principais. As solicitações de API para métodos em tempo real cobram cotas em tempo real. As solicitações de API para métodos de funil cobram cotas de funil. As solicitações de API para métodos do Chat cobram cotas do Chat. Cada solicitação consome apenas um tipo de cota.

Categoria da cota	Métodos da API
Core	runReport, runPivotReport, batchRunReports, batchRunPivotReports, runAccessReport, getMetadata, checkCompatibility, createAudienceExports
Em tempo real	runRealtimeReport
Funil	runFunnelReport
Chat	properties.chat

Cotas de propriedade do Analytics

Todas as solicitações consomem cotas de propriedade.

Nome da cota	Limite de propriedade padrão	Limite de propriedades do Analytics 360
Tokens principais por propriedade por dia	200.000	2.000.000
Tokens principais por propriedade e hora	40.000	400.000
Tokens principais por projeto, propriedade e hora	14.000	140.000
Solicitações simultâneas principais por propriedade	10	50
Erros de servidor principais por projeto, propriedade e hora	10	50
Tokens da API Realtime por propriedade e dia	200.000	2.000.000
Tokens em tempo real por propriedade e hora	40.000	400.000
Tokens em tempo real por projeto, propriedade e hora	14.000	140.000
Solicitações simultâneas em tempo real por propriedade	10	50
Erros de servidor em tempo real por projeto, propriedade e hora	10	50
Tokens de funil por propriedade e dia	200.000	2.000.000
Tokens de funil por propriedade e hora	40.000	400.000
Tokens de funil por projeto, propriedade e hora	14.000	140.000
Solicitações simultâneas de funil por propriedade	10	50
Erros de servidor de funil por projeto, propriedade e hora	10	50
Tokens de chat por propriedade e dia	3.750.000	3.750.000
Tokens de chat por propriedade e hora	500.000	500.000

• As solicitações simultâneas são medidas pelo número de solicitações que estão sendo executadas ao mesmo tempo. Para reduzir a simultaneidade de solicitações, aguarde a conclusão das solicitações anteriores antes de enviar outras.
• Os erros de servidor são os códigos 500 e 503. As cotas de erros de servidor só são cobradas quando uma solicitação resulta em um erro de servidor. Quando as cotas de erros de servidor são esgotadas para um par de projeto e propriedade, todas as solicitações do projeto para a propriedade são bloqueadas. Para ver uma lista completa de respostas de erro, consulte Respostas de erro.
• Cada solicitação consome cota de tokens por propriedade e hora e de tokens por projeto, propriedade e hora. Isso significa que uma propriedade precisa ser acessada por mais de três projetos para que a cota "Tokens por propriedade e hora" seja esgotada antes da cota "Tokens por projeto, propriedade e hora".

Observação: todas as cotas diárias são atualizadas à meia-noite do horário padrão do Pacífico. Todas as cotas por hora são atualizadas em uma hora, mas não necessariamente nos limites de hora inteira.

As propriedades podem fazer 120 solicitações com possível limitação por hora. As dimensões userAgeBracket, userGender, brandingInterest, audienceId e audienceName podem estar sujeitas a limites. Os limites são aplicados para impedir que qualquer pessoa que visualize um relatório deduza as informações demográficas ou os interesses de usuários individuais.

Cota de tokens de propriedade

Os tokens são consumidos a cada solicitação à API Google Analytics Data v1. O número de tokens cobrados depende da complexidade da solicitação. Embora a maioria das solicitações cobre 10 tokens ou menos, as mais complexas (como as consultas do Ask Advisor chat) vão consumir mais.

Fatores que influenciam o consumo de tokens

O custo exato de tokens para uma solicitação é determinado no momento da execução, o que dificulta o cálculo prévio preciso. O custo é influenciado por uma combinação de fatores relacionados à solicitação em si e aos dados subjacentes na propriedade do Google Analytics. Estes fatores podem resultar em custos mais altos:

• Número de linhas: solicitação de um número maior de linhas.
• Número de dimensões e métricas: inclua um número maior de dimensões e métricas.
• Complexidade do filtro: uso de expressões de filtro complexas.
• Duração do período: consulta em períodos mais longos.
• Cardinalidade de dados: dimensões com alta cardinalidade (muitos valores exclusivos, como pagePath, dimensões personalizadas) podem aumentar significativamente o custo de tokens.
• Volume de eventos da propriedade: as consultas em propriedades com um volume maior de eventos podem consumir mais tokens do que a mesma consulta em uma propriedade com menos dados.

Monitorar o uso de tokens

A maneira mais eficaz de determinar o custo de token para suas chamadas de API específicas é incluir o parâmetro "returnPropertyQuota": true no corpo da solicitação (compatível com runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport e runFunnelReport). A resposta da API incluirá o objeto PropertyQuota, que detalha os tokens consumidos por essa solicitação específica e os saldos de cota restantes.

Exemplo de solicitação com 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
}

Exemplo de payload de resposta propertyQuota

Quando "returnPropertyQuota": true é definido, a resposta inclui um objeto propertyQuota em que cada campo contém um QuotaStatus com números inteiros consumed e 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
    }
  }
}

Cada campo em propertyQuota corresponde a uma cota em Cotas de propriedade do Analytics. A cobrança de tokens de uma única solicitação de API é deduzida simultaneamente de tokensPerDay, tokensPerHour e tokensPerProjectPerHour. Se algum bucket de cota chegar a 0 restante, as solicitações seguintes para essa propriedade vão retornar um erro 429 RESOURCE_EXHAUSTED.

Práticas recomendadas para evitar erros 429 RESOURCE_EXHAUSTED

• Monitore os saldos de remaining de forma dinâmica: inspecione propertyQuota.tokensPerProjectPerHour.remaining e propertyQuota.tokensPerHour.remaining nas respostas e limite ou pause jobs em segundo plano não urgentes quando os tokens restantes ficarem abaixo de um limite de segurança.
• Agrupar consultas relacionadas: use batchRunReports ou batchRunPivotReports para agrupar até cinco relatórios em uma única chamada HTTP e reduzir a sobrecarga de ida e volta HTTP. Cada relatório em um lote ainda conta individualmente para as cotas de token e concurrentRequests.
• Reduza a complexidade e a cardinalidade das consultas: limite as solicitações apenas às dimensões e métricas necessárias, reduza dateRanges sempre que possível e evite combinar várias dimensões de alta cardinalidade (como pagePath ou fullPageUrl) em consultas de sondagem frequentes.
• Controlar a simultaneidade de solicitações: coloque as solicitações em fila ou limite o tamanho do pool de workers para que as solicitações em andamento fiquem abaixo do limite de concurrentRequests (10 para o Standard, 50 para o Analytics 360).
• Implemente a espera exponencial com limites de repetição: se uma solicitação falhar com 429 RESOURCE_EXHAUSTED, 500 INTERNAL ou 503 UNAVAILABLE, tente novamente usando a espera exponencial truncada, conforme descrito em Respostas de erro.

Consumo e monitoramento de tokens de chat

Para solicitações do Ask Advisor chat, os tokens representam os custos de computação, raciocínio e recuperação de dados subjacentes do modelo. O consumo de tokens do Chat é influenciado por:

• Escopo de consulta e análise: complexidade e amplitude da análise solicitada.
• Tokens de entrada e saída do modelo: volume de dados contextuais processados e narrativa de resposta gerada.
• Tokens de raciocínio: etapas de raciocínio do modelo necessárias para sintetizar as descobertas.
• Latência de execução: tempo de processamento necessário para análises de dados em várias etapas.

Para monitorar o uso de tokens de chat, defina "returnPropertyQuota": true no seu ChatRequest. A resposta vai incluir o objeto PropertyChatQuota, que contém os campos tokensPerDay e tokensPerHour com os saldos consumidos e restantes.