Limites de taxa

Para fornecer serviços confiáveis aos usuários da Google AdWords API de todo o mundo, usamos um algoritmo de intervalo de token para medir as solicitações e determinar a taxa de consultas por segundo (QPS, na sigla em inglês). This is intended to prevent malicious or out–of-control software from overwhelming the AdWords API servers and affecting other users.

Por exemplo, se um cliente de saída gerou acidentalmente milhares de tópicos para fazer chamadas simultâneas à Google AdWords API, os servidores da Google AdWords API notarão e retornarão um RateExceededError solicitando que o software chamador desacelere.

É importante lembrar que os limites de taxa oscilam em função das diferentes variáveis, incluindo o carregamento do servidor. Por isso, não recomendamos um limite de QPS fixo para os desenvolvedores. É extremamente importante entender como gerenciar o RateExceededError e desenvolver seu software tendo em mente os limites de taxa.

Este guia traz mais detalhes para ajudar você a entender o RateExceededError e como evitar ultrapassar o limite de taxa.

História

Em versões mais antigas da Google AdWords API, as solicitações feitas além do limite eram colocadas em fila no servidor da API até que pudessem ser executadas, resultando em tempos de execução muito longos para algumas solicitações. Em vez de bloquear o cliente por um longo período, a API atual resolve a falha rapidamente e retorna um RateExceededError. Acreditamos que esse mecanismo de feedback importante ajuda você a perceber o problema de modo a ajustar seus aplicativos adequadamente.

Tipos de limites de taxa

Reconhecemos que seu aplicativo cliente da Google AdWords API às vezes pode ultrapassar o limite e receber um RateExceededError devido a fatores que não estão totalmente sob seu controle. É importante ressaltar que não há penalidades por isso. O erro RateExceededError geralmente é transitório e resolvido automaticamente após 30 segundos de inatividade.

Há vários tipos diferentes de limites de taxa que podem ser executados pelo servidor. Um aplicativo cliente pode exceder um limite de taxa dentro do escopo do token de desenvolvedor da conta de administrador ou da conta do Google AdWords. Dentro de cada escopo, em vez de um rigoroso limite de QPS, os limites de taxa são avaliados em termos de solicitações por minuto, operações por minuto e/ou outros tipos de limites de taxa. Isso gera tráfego estável e dinâmico para a Google AdWords API. O escopo e o nome do limite de taxa são retornados como parte do RateExceededError.

Limite operacional com base no nível de acesso

Há apenas um tipo de limite de taxa que não oscila: o limite operacional com base no nível de acesso do seu token de desenvolvedor. Existem dois níveis de acesso: básico e padrão. Uma conta com nível de acesso básico tem limites de 10.000 operações e 1.000 downloads de relatórios por dia. Por padrão, é atribuído um token de desenvolvedor recém-aprovado ao nível de acesso básico. Se você pretende executar mais de 10.000 operações ou fazer mais de 1.000 downloads de relatórios por dia, preencha o Formulário de inscrição para ter acesso padrão à AdWords API para se inscrever no nível de acesso padrão. Não há custos para nenhum dos níveis de acesso. Consulte a planilhas de tarifas para determinar como as operações são contabilizadas.

Com exceção do limite operacional, todos os outros limites de taxa podem oscilar. Portanto, é importante gerenciar o RateExceededError no seu aplicativo.

Elementos do RateExceededError

Vejamos o RateExceededError em mais detalhes (ele contém três campos muito importantes):

  • rateScope: o escopo da taxa que foi excedida, que pode ser ACCOUNT ou DEVELOPER.
  • rateName: contém o nome do limite de taxa que foi excedido. O valor pode ser, por exemplo, RequestsPerMinute.
  • retryAfterSeconds: contém o número mínimo de segundos que seu aplicativo deve aguardar antes de tentar processar a solicitação novamente. Recomendamos a aplicação de um multiplicador aleatório (por exemplo, um valor variável entre 1 e 2, incluindo ambos) ao retryAfterSeconds quando você determinar o período de espera em segundos. Se seus programas enviarem solicitações em paralelo (por exemplo, por meio de várias conversas), é importante que eles não enviem novas solicitações ao mesmo tempo após o período de espera.

Se seu aplicativo estiver excedendo o limite de taxa com uma grande frequência, você precisará analisar rateScope e rateName para implementar uma estratégia de otimização mais permanente no seu aplicativo.

Escopo da conta x escopo do desenvolvedor

O valor do escopo da taxa pode ser ACCOUNT ou DEVELOPER. Isso indica se o limite de taxa foi excedido no nível de uma conta do Google AdWords ou do token de desenvolvedor.

Escopo da taxa de token de desenvolvedor

Cada conta de administrador do Google AdWords inscrita para usar a AdWords API tem um único token de desenvolvedor, e cada solicitação que você faz provavelmente está associada a esse token de desenvolvedor. Se o QPS combinado de todas as solicitações de clientes que usam o mesmo token de desenvolvedor excede um determinado limite de taxa, o RateExceededError pode ser retornado indicando o escopo da taxa de desenvolvedor.

Por exemplo, o software do cliente pode receber um RateExceededError pelo escopo da taxa do token de desenvolvedor se uma conta de administrador gerenciar 100 contas do Google AdWords, e houver várias instâncias do software do cliente usando o mesmo token de desenvolvedor para fazer um total de centenas de solicitações por segundo em vários processos, conversas ou máquinas.

Escopo da taxa da conta

Se o mesmo aplicativo faz um número elevado de solicitações por segundo em uma única conta do Google AdWords gerenciada pela conta de administrador, o servidor da AdWords API pode retornar um RateExceededError por exceder o limite de taxa no escopo da conta. Isso pode acontecer, por exemplo, se seu aplicativo cliente gerar vários segmentos com o objetivo de executar um número excessivo de operações mutate() para uma única conta do Google AdWords.

Lembre-se de que esse limite de taxa em todo o escopo da taxa da conta é medido em todas as solicitações para uma única conta do Google AdWords, independentemente do token de desenvolvedor usado para fazer a solicitação.

Digamos que uma única conta do Google AdWords seja gerenciada por cinco contas de administrador diferentes. É possível que todas as cinco contas de administrador façam solicitações para essa mesma conta do Google AdWords ao mesmo tempo. Se o QPS de todas as contas de administrador combinadas exceder o limite, os clientes receberão RateExceededError no escopo da taxa da conta.

Nome da taxa e por que ele é importante

Além de entender o escopo da taxa, é importante também entender o tipo de limite de taxa que foi excedido. O tipo de limite de taxa é retornado no campo rateName. Os nomes de limite de taxa normalmente vistos são:

  • RequestsPerMinute
  • OperationsPerMinute
Diferença entre uma solicitação e uma operação

Qual é a diferença entre RequestsPerMinute e OperationsPerMinute? Cada chamada de serviço SOAP é contada como uma solicitação. Por exemplo, sempre que você chamar CampaignService.mutate(), ela será contada como uma solicitação. No entanto, na solicitação de modificação, você pode ter passado de 100 CampaignOperations (isso seria contabilizado como 100 operações).

No exemplo acima, embora você possa ter evitado um limite de taxa de RequestPerMinute combinando várias operações em uma solicitação, ainda pode atingir um limite de taxa de OperationsPerMinute.

Você pode encontrar mais exemplos de como as operações são contadas na página Planilha de tarifas.

Casos extremos

Embora os nomes de taxa acima sejam mais comuns, é importante lembrar que você pode ultrapassar outros tipos de limites de taxa existentes. Se você tiver esses problemas, informe-nos no Fórum da AdWords API.

Desacelerar

Se seu aplicativo receber um RateExceededError, será a hora de desacelerar. Se você não fizer isso, poderá atrasar ainda mais a capacidade do aplicativo de se recuperar desse erro. Uma das maneiras mais simples de fazer isso é honrar o valor RateExceededError.retryAfterSeconds ao repetir a solicitação e/ou prosseguir com outras solicitações.

Por exemplo, em Java, uma das maneiras mais simples de pausar seu tópico antes de processar outra solicitação é fazer um Thread.sleep().

try {
  ...
} catch (ApiException e) {
  for (ApiError error : e.getErrors()) {
    if (error instanceof RateExceededError) {
      RateExceededError rateExceeded = (RateExceededError) error;
      Thread.sleep(rateExceeded.getRetryAfterSeconds() * 1000);
    }
  }
  ...
}

Embora essa abordagem seja simples e direta, talvez não seja ideal para alcançar um rendimento geral melhor e deve ser usada como a última linha de defesa.

Há várias maneiras de reduzir as chances de ultrapassar o limite de taxa. A criação de um aplicativo cliente mais robusto é facilitada quando você conhece melhor conceitos de Enterprise Integration Patterns (EIP, na sigla em inglês) como mensagens, nova devolução e otimização.

Veremos essas práticas recomendadas na próxima seção. Lembre-se de que, mesmo quando as práticas de redução são aplicadas, ainda é importante poder gerenciar o RateExceededError.

Assumir o controle

É possível assumir o controle do seu aplicativo e evitar ocorrências de RateExceededError o máximo possível. Para fazer isso, reduza ativamente o número de solicitações e de QPS de otimização do lado do cliente.

Veja a seguir algumas práticas recomendadas, ordenadas por complexidade, com as estratégias mais simples na parte superior e arquiteturas mais robustas, porém sofisticadas, em seguida:

  • Limite de threads simultâneos
  • Solicitações em lotes
  • Uso de BatchJobService
  • Otimização / limitador de taxa
  • Intercalar solicitações para contas diferentes
  • Enfileiramento
  • Diferenciar novas contas x contas estabelecidas

Limite de threads simultâneos

Geralmente, a principal causa de um RateExceededError é a geração de um número excessivo de threads por parte do aplicativo cliente, e todos esses threads chamam a AdWords API ao mesmo tempo. Não limitamos o número de threads simultâneos de um aplicativo cliente, mas o envio de solicitações simultâneas por meio de um número de threads ilimitado pode facilmente exceder o limite de solicitações por segundo no nível do token de desenvolvedor.

É recomendado definir um limite superior razoável para o número total de threads simultâneos que farão solicitações (em todos os processos e máquinas). Para otimizar sua taxa de transferência sem exceder o limite de taxa, aumente esse valor a partir do limite definido.

Além disso, você pode avaliar a possibilidade de otimizar o QPS do lado do cliente em todos os tópicos (ver Otimização / limitador de taxa).

Solicitações em lotes

Sempre que possível, avalie a possibilidade de enviar várias solicitações em lote em uma única solicitação. Isso se aplica mais às chamadas de mutate(). Por exemplo, se você está atualizando o status de várias instâncias de AdGroupAd (em vez de chamar mutate() uma vez para cada AdGroupAd), é possível chamar mutate() e passar vários AdGroupAdOperation de uma só vez. Consulte nossas Práticas recomendadas para ver alguns exemplos adicionais, bem como as melhores maneiras de agrupar operações.

Ao combinar várias operações em uma única solicitação, é importante lembrar que a maioria das solicitações são atômicas. Se uma operação falhar, toda a solicitação falhará e nada será atualizado. Para alterar esse comportamento, use o recurso de falha parcial.

Por fim, embora as solicitações em lote reduzam o número de solicitações totais e o limite de taxa de solicitações por minuto, elas podem acionar o limite da taxa de operações por minuto, se você executar um grande número de operações para uma única conta.

Uso de BatchJobService

Para tarefas de longa duração ou para processar um grande número de operações ou se um grande número de operações for dividido entre vários serviços, avalie a possibilidade de usar o BatchJobService. O serviço BatchJobService pode programar e executar milhares de operações por você, de forma assíncrona, na nuvem do Google. Você só precisa pesquisar o resultado para ver se a tarefa foi concluída.

Consulte o guia de processamento em lote para ver mais detalhes.

Otimização / limitador de taxa

Além de limitar o número total de conversas do aplicativo cliente, você também pode implementar limitadores de taxa no lado do cliente. Tal estratégia pode garantir que todas as conversas dos seus processos e/ou clusters sejam regidos por um limite específico de QPS do lado do cliente.

Por exemplo, você pode conferir o limitador de taxa Guava ou implementar seu próprio algoritmo de intervalo de token que funciona para um ambiente em cluster. Por exemplo, é possível gerar tokens e armazená-los em um dispositivo de armazenamento transacional compartilhado, como um banco de dados. Nesse caso, cada cliente terá que adquirir e consumir um token antes do processamento da solicitação. Se os tokens forem usados, o cliente terá que aguardar a criação do próximo lote de tokens.

Na maioria dos casos, a otimização evita que você exceda os limites de taxa no escopo do token de desenvolvedor.

Intercalar solicitações para contas diferentes

Se você exceder o limite de taxa no escopo da conta, poderá limitar a taxa de QPS da conta no lado do cliente. No entanto, isso pode ser complicado quando você tem milhares de contas para gerenciar. Uma estratégia mais simples é intercalar as solicitações com base nas contas.

Por exemplo, se você estiver executando 5.000 operações mutate() para 10 contas, uma maneira de fazer isso é enviar sequencialmente operações em lote para a Conta 1 primeiro, depois para a Conta 2 e, por fim, para a Conta 3:

  1. Envie 500 operações de modificação para a Conta 1 (e repita 10 vezes para 5.000 operações).
  2. Envie 500 operações de mutação para a Conta 2 (e também faça isso 10 vezes).
  3. … (até finalizar as 10 contas).

Embora essa abordagem seja simples, você pode exceder o limite de taxa no escopo da conta para o número de operações por minuto.

Ao intercalar as contas, as solicitações teriam esta aparência:

  1. Enviar 500 operações de mutação para a Conta 1
  2. Enviar 500 operações de mutação para a Conta 2
  3. Enviar 500 operações de mutação para a Conta 3
  4. … (até finalizar as 10 contas)
  5. Enviar 500 operações de mutação para a Conta 1
  6. Enviar 500 operações de mutação para a Conta 2
  7. … (até finalizar as 5.000 operações para cada conta)

Embora esse exemplo ilustre como intercalar as solicitações com base nas contas, você também deve verificar se o BatchJobService atende às suas necessidades. Consulte o guia de processamento em lote para mais informações.

Enfileiramento

Uma fila de mensagens é a melhor solução para a distribuição do carregamento de operações, pois também controla as taxas de solicitações e consumidores. Existem diversas opções de fila de mensagens disponíveis (algumas de código aberto, outras proprietárias) e muitas delas podem funcionar com idiomas diferentes.

Quando você usa as filas de mensagens, é possível que vários produtores enviem mensagens para a fila e vários consumidores processem essas mensagens. Para implementar os otimizadores no lado dos consumidores, limite o número de consumidores simultâneos ou implemente limitadores de taxa ou otimizadores para os produtores ou consumidores.

Por exemplo, se um consumidor de mensagens encontra um RateExceededError, ele pode retornar a solicitação de volta para a fila para ser repetido. Ao mesmo tempo, o consumidor também pode notificar todos os outros consumidores para que pausem o processamento por alguns segundos com a finalidade de se recuperar do erro.

Diferenciar fila ou limitador de taxa para novas contas x contas estabelecidas

Quando você implementa estratégias de filas ou limitadores de taxa, é importante levar em consideração que uma nova conta do Google AdWords pode ter um limite de taxa significativamente mais restritivo (ou seja, com um QPS menor) do que as contas existentes. Assim, se sua organização cria novas contas constantemente e tem um grande número de contas mais antigas para gerenciar, você deve avaliar a possibilidade de usar limitadores de taxa ou otimizadores diferentes para os dois tipos de conta.

Dessa forma, você pode maximizar seu rendimento para os dois tipos de conta, em vez de ficar limitado pela conta com o QPS mais baixo.

Normalmente, os limites mais restritivos em novas contas do Google AdWords são afrouxados quando a conta tem anúncios publicados.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.