Gerenciamento de cotas da API Google Analytics Data

Minhaz Kazi, mediador de desenvolvedores, Google Analytics – fevereiro de 2023

Para desenvolver aplicativos usando a API Data do Google Analytics, você precisa entender como funcionam as cotas e os limites da API. Em aplicativos bem projetados, é menos provável que os usuários atinjam os limites de cota. Algumas das práticas recomendadas também ajudam a executar consultas eficientes na API. Isso pode acelerar a geração de relatórios e os painéis do seu aplicativo e melhorar a experiência do usuário. Neste artigo, falamos sobre o sistema de cotas e as práticas recomendadas para implementar a API Data do Google Analytics.

Noções básicas sobre o sistema de cotas da API Data do Google Analytics

Como o Google Analytics é usado por milhões de desenvolvedores e usuários, a cota em solicitações de API evita que o sistema processe mais dados do que consegue, garantindo a distribuição equitativa dos recursos. A API Data utiliza um sistema de token buckets para gerenciar as cotas nas propriedades do Google Analytics 4. Para entender o conceito, imagine um bucket que armazena um determinado número de tokens. Primeiro, uma solicitação de API vai verificar nesse bucket se ainda há tokens disponíveis. Se não houver, vai ocorrer uma falha. Se houver, a solicitação vai ser executada, consumindo um ou mais tokens a depender da complexidade dela. Os tokens são repostos no bucket até o nível máximo, em intervalos de tempo fixos.

Há três categorias de cota, dependendo do método da API Data usado:

• Em tempo real (para runRealtimeReport)
• Funil (para runFunnelReport)
• Core (para todos os outros métodos)

Os métodos da API Data vão conferir se há tokens de cota em vários buckets:

1. Por propriedade e dia
2. Por propriedade e hora
3. Por projeto, propriedade e hora
4. Solicitações simultâneas por propriedade
5. Erros de servidor por projeto, propriedade e hora

Esses cinco buckets são verificados sempre que é feita uma solicitação da API Data em uma propriedade. Se algum deles estiver vazio, vai ocorrer falha imediata da solicitação com um erro 429. Se nenhum estiver vazio, vai ser consumido um único token do bucket Solicitações simultâneas por propriedade e a solicitação de API vai ser executada. A quantidade de tokens consumidos de cada um dos três primeiros buckets após a execução vai depender da complexidade da solicitação, e um token será reposto em Solicitações simultâneas por propriedade.

A cota referente a Por projeto, propriedade e hora garante que o término da cota para um ou mais usuários do aplicativo não afete os demais. Nesse caso, projeto se refere ao projeto do GCP. A cota para Por propriedade e hora geralmente é quatro vezes maior do que Por projeto e hora. Então, no caso dos usuários finais, uma propriedade precisa ser acessada por pelo menos quatro projetos diferentes para que a cota do bucket Por propriedade e hora acabe. Aplicar uma cota no nível do projeto e da propriedade limita os problemas a uma única propriedade, sem afetar outras propriedades que o aplicativo acessa.

Aviso: não é recomendado que os desenvolvedores fragmentem tokens de cota em vários projetos de API. Isso viola os Termos de Serviço das APIs do Google.

A cota para Erros de servidor se refere a respostas da API com códigos 500 ou 503. Se o aplicativo gerar muitos erros ao acessar uma propriedade, a cota do bucket Erros de servidor por projeto, propriedade e hora vai ser atingida.

Todos os tokens são repostos no nível máximo em intervalos estabelecidos. Para informações atualizadas, consulte Cotas da API Data do Google Analytics. Por exemplo, os métodos Core recebem uma cota de 1.250 tokens no bucket Por projeto, propriedade e hora. Supondo que uma solicitação média consuma 10 tokens, seu aplicativo vai fazer 125 solicitações Core por hora para uma propriedade padrão e 10 vezes esse valor (1.250 solicitações Core) para uma propriedade do Analytics 360. Um dos principais benefícios das propriedades do Analytics 360 é o limite maior de tokens de cota.

Como o consumo de tokens dos três primeiros buckets depende da complexidade da solicitação, é difícil prever o uso exato antes da execução. Estas atividades costumam aumentar a complexidade de uma solicitação, usando mais tokens:

• Solicitar mais dimensões
• Consultar um intervalo de tempo maior
• Incluir dimensões com maior cardinalidade
• Consultar uma propriedade com maior contagem de eventos

Portanto, a mesma consulta para duas propriedades distintas pode ter um consumo de tokens completamente diferente, porque a cardinalidade das dimensões ou o volume de tráfego pode variar. Já as propriedades com níveis de tráfego e configurações semelhantes costumam ter um uso de tokens parecido. Essa é a uma boa premissa para prever o uso de tokens durante as fases de planejamento e design do aplicativo.

Observação: se você já usou a API Reporting para o Universal Analytics, sabe que ela aplica a cota no nível do projeto do aplicativo ou da API. Para a API Data, isso é feito no nível da propriedade do Google Analytics e também do projeto da API.

Como monitorar o uso de cotas

Para monitorar o uso de cotas e informar o usuário final, adicione "returnPropertyQuota": true ao corpo da solicitação de API. O objeto PropertyQuota vai ser retornado como resposta, mostrando os valores de consumo e o status da cota restante para os cinco buckets. Confira um exemplo de corpo e resposta de solicitação:

Solicitação

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

Resposta

{
  "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",
  ...
}

Assim, depois de cada solicitação sem erros da API Data, você vai saber a quantidade consumida e o quanto ainda resta da cota para a propriedade. Também é possível disponibilizar essas informações ao usuário na interface do aplicativo.

Observação: no momento, é preciso executar uma solicitação da API Data para acessar o objeto PropertyQuota. Se o token bucket da cota de uma propriedade já tiver acabado, vai ocorrer uma falha na solicitação com um erro 429 e o objeto PropertyQuota não vai aparecer na resposta. Se isso afetar seu aplicativo e você achar que precisa de outra forma para acessar as informações de cota, marque esta solicitação de recurso com +1 no Issue Tracker.

Gerenciamento de cotas

Recomendamos que você implemente as seguintes práticas de gerenciamento de cotas para aproveitar ao máximo a API Data. Além disso, com o upgrade das suas propriedades para o 360, seu aplicativo vai acessar mais dados usando a API.

Práticas recomendadas

Há duas maneiras de reduzir o uso da cota do aplicativo:

• Enviar menos solicitações de API
• Enviar solicitações de API mais simples

Com base nisso, você pode implementar estas práticas:

• Armazenamento em cache: implementar uma camada de armazenamento em cache melhora a usabilidade e o gerenciamento de cotas do aplicativo. Mesmo que o Google Analytics armazene em cache suas solicitações de API, as solicitações repetidas ainda vão consumir tokens da cota. Ao armazenar a resposta da API em cache, você reduz drasticamente as repetições. Por exemplo, os dados intradiários de propriedades padrão podem ficar no cache por quatro horas ou mais. Consulte Atualização de dados do Google Analytics.
• Mesclar solicitações: tente mesclar várias solicitações de API em apenas uma. Por exemplo, cinco solicitações de dados em um período de dois dias podem usar três vezes mais tokens da cota do que uma única solicitação em um período de 10 dias. Se você tiver várias solicitações com apenas uma dimensão diferente, mescle-as.
• Simplificar as solicitações: limite as solicitações à quantidade mínima de dados necessários para o aplicativo e o usuário. Usar muitas linhas/colunas ou critérios de filtro complexos consome mais tokens da cota. Normalmente, períodos mais longos gastam mais. Por exemplo, se você mudar o período de 28 dias para 365 dias, vai consumir três vezes mais tokens. Considere também usar dimensões com cardinalidade mais baixa sempre que possível, por exemplo, chame dateHour em vez de dateHourMinute.
• Usar limit de forma eficiente: mudar o limit na solicitação de API para reduzir o número de linhas retornadas não afeta significativamente os tokens consumidos. Por exemplo, cinco solicitações com limites de 10 mil linhas podem consumir cinco vezes mais tokens do que uma única com limite de 50 mil.
• Usar a categoria de método correta: como mencionado acima, os limites de cota são distribuídos entre três categorias de método. Usar o método certo para o caso específico pode economizar a cota de outras categorias. Por exemplo, em vez de criar seu próprio funil no aplicativo com dados dos métodos Core, utilize runFunnelReport.
• Atualizar as configurações padrão: ao criar ou personalizar relatórios na plataforma, os usuários podem manter as opções padrão mostradas pelo app e só fazer mudanças durante o tempo de execução. Se o aplicativo tiver um período padrão de 365 dias e o usuário sempre analisar um relatório de 28 dias, o consumo da cota vai ser maior do que o necessário. Limite os intervalos e as seleções nas configurações padrão, deixando que os usuários escolham as configurações ideais para cada caso de uso. Em algumas situações, também é possível restringir quais padrões eles podem mudar.
• Enfileirar solicitações e incluir carregamento lento: preste atenção no limite de tokens em Solicitações simultâneas por propriedade. O aplicativo não deve enviar muitas solicitações ao mesmo tempo. Se ele tiver muitos elementos da interface, resultando em um número alto de solicitações de API, considere paginar a interface, incluir carregamento lento e enfileirar solicitações com espera exponencial para novas tentativas. Implemente o método returnPropertyQuota para monitorar o uso de tokens em Solicitações simultâneas por aplicativo.

Como gerenciar a experiência e as expectativas do usuário

• Avise o usuário quando ele estiver prestes a executar consultas que podem resultar em alto consumo de tokens, por exemplo, consultas com várias dimensões de alta cardinalidade ou um período longo. Ao mostrar avisos e prompts de confirmação, você pode impedir que os usuários façam mudanças desnecessárias nos relatórios e ajuda a limitar o escopo das consultas.
• Para soluções de relatórios personalizados, inclua recursos que ajudem os usuários a entender como usar a consulta dos elementos. Por exemplo, inclua uma vista de depuração que detalha o consumo de tokens da cota em cada caso.
• Adicione detalhes sobre o tipo específico de erro de cota e recomende ações do usuário.
• Você tem mais flexibilidade com as propriedades do Google Analytics 360, já que elas têm um limite 5 a 10 vezes maior do que as propriedades padrão.

No Google Analytics 4, não é possível aumentar as cotas da API Data acima do padrão. O Google Analytics 360 oferece limites maiores para as cotas das propriedades do Google Analytics 4. Se os usuários continuarem atingindo os limites de cota mesmo com a implementação das práticas recomendadas, devem considerar fazer o upgrade das propriedades para o 360. Outra opção é usar o BigQuery Export do Google Analytics. Assim, eles podem exportar os dados no nível do evento para o BigQuery e executar as próprias análises.

Se você tiver outras dúvidas sobre as cotas da API Data, acesse o GA Discord ou faça sua pergunta no Stack Overflow. Para solicitações de recursos relacionados à API Data, acesse o Issue Tracker.