Práticas recomendadas

Este guia explica algumas práticas recomendadas que você pode implementar para otimizar a eficiência e o desempenho dos seus aplicativos da Google AdWords API.

Manutenção contínua

Para garantir que seu aplicativo seja executado sem interrupções:

  • Keep your developer contact email in the AdWords API Center up–to-date. Ele é o alias que usamos para entrar em contato com você. Se não conseguirmos falar com você sobre a conformidade com os Termos e Condições da API, seu acesso à API poderá ser revogado sem aviso prévio. Evite utilizar um endereço de e-mail pessoal vinculado a uma conta individual ou não monitorada.

  • Para ser informado sobre problemas, como alterações de produtos, período de inatividade devido a uma manutenção, datas de suspensão de uso e assim por diante, inscreva-se nos seguintes canais:

O fórum é monitorado regularmente pela equipe da Google AdWords API. Por isso, ele é o lugar ideal para fazer perguntas sobre a API.

  • Mantenha seu aplicativo em conformidade com os Termos e Condições (T&C) e os recursos mínimos obrigatórios (RMF, na sigla em inglês) da Google AdWords API. Se necessário, a equipe de conformidade e revisão de tokens entrará em contato com você por e-mail. Se você tiver dúvidas sobre os T&C ou os RMF, entre em contato com a equipe de revisão. Para isso, responda ao e-mail enviado a você no processo de revisão do seu aplicativo de token de desenvolvedor.

Otimização

Operações em lote

A realização de uma solicitação à API acarreta vários custos fixos, como latência de rede de ida e volta, processamento de serialização e desserialização e chamadas para sistemas de back-end. Para diminuir o impacto desses custos fixos e aumentar o desempenho geral, a maioria dos métodos mutate() na API são projetados para aceitar uma variedade de operações. Ao buscar várias operações em cada solicitação, é possível reduzir os custos fixos associados e o número de solicitações que você faz. Se possível, evite fazer solicitações com apenas uma operação.

Por exemplo, suponha que você esteja adicionando 50.000 palavras-chave a uma campanha em vários grupos de anúncios. Em vez de fazer 50.000 solicitações com 1 palavra-chave cada, faça 100 solicitações com 500 cada ou até mesmo 10 solicitações com 5.000 cada. Há limites para o número de operações permitidas em uma solicitação. Portanto, pode ser necessário ajustar o tamanho do lote para atingir o desempenho ideal.

Outra vantagem de fazer poucas solicitações, porém maiores, é a probabilidade menor do seu aplicativo encontrar um limite de taxa com base em uma solicitação.

Operações de grupos

Operações que segmentam o mesmo grupo de anúncios ou a mesma campanha processarão mais rápido que o mesmo número de operações segmentando vários grupos de anúncios ou campanhas diferentes. O agrupamento de operações que segmentam o mesmo grupo de anúncios ou a mesma campanha reduz o número total de grupos de anúncios ou campanhas segmentadas na solicitação, o que melhora o desempenho geral.

Solicitações simultâneas para um grupo de anúncios ou uma campanha podem gerar um erro de CONCURRENT_MODIFICATION. Agrupar operações que modificam o mesmo grupo de anúncios ou a mesma campanha em uma única solicitação diminui a chance de isso acontecer.

Veja o exemplo acima, que adiciona 50.000 palavras-chave a uma campanha em vários grupos de anúncios. Antes de dividir as operações em lotes, uma abordagem simples consiste em classificar as palavras-chave pelo grupo de anúncios que elas segmentam. Isso aumentará a chance de todas as palavras-chave de um grupo de anúncios se enquadrarem na mesma solicitação, além de diminuir o número total de grupos de anúncios segmentados em uma única solicitação. É possível utilizar abordagens mais avançadas para garantir que as operações relacionadas sejam agrupadas no menor número possível de solicitações sem perder lotes grandes.

Reutilizar tokens de acesso

Reutilizar o mesmo token de acesso do OAuth2 em sequências e processos reduz a sobrecarga de atualizações periódicas de tokens, além de diminuir a probabilidade do seu aplicativo ter um limite de taxa devido a um número excessivo de atualizações do token. Saiba mais sobre a otimização de solicitações do OAuth2.

Enviar objetos escassos

Quando os objetos são enviados para a API, os campos precisam ser desserializados, validados e armazenados no banco de dados. Enviar objetos completos quando você só deseja atualizar alguns campos pode resultar em mais tempo de processamento e desempenho inferior. Para amenizar isso, a Google AdWords API é compatível com atualizações escassas. Assim, você pode preencher apenas os campos que deseja alterar ou sejam necessários em um objeto. Os campos que não forem preenchidos ou tiverem valores nulos não serão alterados. Isso aumentará o desempenho das suas solicitações.

Por exemplo, um aplicativo que atualiza lances no nível da palavra-chave pode aproveitar as atualizações escassas, já que apenas os campos adGroupID, criterionID e de lances precisariam ser preenchidos. Em um teste com 150 palavras-chave, houve um aumento de 20% no desempenho ao usar atualizações escassas em vez de enviar objetos completamente preenchidos.

Usar compactação

A Google AdWords API é compatível com a compactação gzip em mensagens de SOAP em solicitações e respostas. Para ativar a compactação gzip em uma resposta, inclua estes dois cabeçalhos HTTP na sua solicitação:

  • User-Agent: contendo a string "gzip"
  • Accept-Encoding: com o valor "gzip"

Exemplo:

User-Agent: My App (gzip)
Accept-Encoding: gzip

Se você estiver usando uma biblioteca cliente, consulte a documentação dela sobre como ativar a compactação.

Tratamento e gerenciamento de erros

Durante o processo de desenvolvimento, você provavelmente encontrará erros. Esta seção descreve as considerações e estratégias para o gerenciamento de erros no seu aplicativo.

Além dessa seção, consulte o guia de solução de problemas para mais informações sobre como lidar com erros.

Diferenciar origens de solicitação

Alguns aplicativos são principalmente interativos. Eles enviam chamadas diretas de API em resposta a ações iniciadas pelo usuário em uma IU. Outros aplicativos funcionam principalmente off-line. Eles enviam chamadas de API como parte de um processo periódico de back-end. Muitos aplicativos combinam os dois. Ao considerar o gerenciamento de erros, pode ser útil diferenciar esses diferentes tipos de solicitação.

No caso de solicitações iniciadas pelo usuário, sua principal preocupação deve ser oferecer uma boa experiência aos seus usuários. Use o erro específico que ocorreu para fornecer o máximo de contexto possível ao usuário na IU. Quando possível, ofereça etapas simples para que ele solucione o erro (veja sugestões abaixo).

No caso de solicitações iniciadas pelo back-end, implemente gerenciadores para os diferentes tipos de erro que seu aplicativo poderá encontrar (veja sugestões abaixo). Sempre inclua um gerenciador padrão para resolver erros incomuns ou inéditos. Uma boa abordagem para um gerenciador padrão é adicionar a operação com falha e o erro a uma fila. Nessa fila, um operador humano os revisará e determinará uma solução adequada.

Diferenciar tipos de erro

Abaixo, há quatro categorias amplas de erro. É preciso lidar com cada uma delas de maneira diferente. Elas não incluem todos os erros possíveis, e alguns podem até se enquadrar em mais de uma categoria. No entanto, elas são um possível ponto de partida para estruturar o tratamento de erros do seu aplicativo. Consulte a documentação Erros comuns para conferir mais detalhes sobre um erro específico.

  1. Erros de autenticação e autorização

    • A autenticação se refere à permissão que seu aplicativo recebeu de um usuário para acessar o Google AdWords e agir em nome dele. A autenticação é gerenciada por meio de credenciais geradas pelo fluxo do OAuth2.

    • A autorização se refere à permissão que seu aplicativo (autenticado e atuante como usuário) tem para trabalhar com os dados específicos do Google AdWords que ele está tentando editar ou gravar.

    O motivo mais comum para o surgimento de um erro de autenticação cuja causa está fora do seu alcance é a revogação da permissão concedida por um usuário autenticado. Isso impede que seu aplicativo aja em nome desse usuário. Por exemplo, se seu aplicativo gerencia contas diferentes do Google AdWords para clientes independentes e os autentica separadamente ao gerenciar a conta de cada um deles, o cliente poderá revogar o acesso do seu aplicativo a qualquer momento. Dependendo de quando seu acesso for revogado, a API poderá retornar diretamente um erro de AuthenticationError.OAUTH_TOKEN_REVOKED. Outra possibilidade é a de os objetos de credencial integrados nas bibliotecas cliente gerarem uma exceção de revogação de token. Em ambos os casos, caso seu aplicativo tenha uma IU para os seus clientes, ele poderá solicitar o reinício do fluxo do OAuth2 para restabelecer a permissão que seu aplicativo possui para agir em nome deles.

    Outro motivo comum para o surgimento de um erro de autorização cuja causa está fora do seu alcance é devido a alterações na hierarquia da sua Conta de administrador. Geralmente, os aplicativos que trabalham com uma única hierarquia de Conta de administrador realizam a autenticação como usuário administrador dessa conta de nível superior. Isso ocorre porque o usuário tem permissão para acessar todas as subcontas na hierarquia. Se o usuário de uma subconta remover o vínculo de administrador, seu aplicativo receberá um erro de AuthorizationError.USER_PERMISSION_DENIED ao tentar acessar essa conta. Você pode usar o ManagedCustomerService para verificar se a subconta foi removida da hierarquia.

    Outro motivo para o surgimento de um erro de autorização é a alteração dos diretos de acesso do usuário com o qual seu aplicativo realizou a autenticação. Por exemplo, suponha que outro usuário com direitos de administrador na conta do Google AdWords altere os direitos do usuário autenticado do seu aplicativo para "Somente leitura". Nesse caso, todas as solicitações modificadas falharão e exibirão um erro de AuthorizationError.USER_HAS_READONLY_PERMISSION.

    Para qualquer exemplo, seu aplicativo poderá fornecer instruções ao usuário ou encaminhar a solução do problema a um gerente da conta.

  2. Erros que permitem uma nova tentativa

    Alguns erros indicam um problema temporário que pode ser resolvido ao repetir a solicitação após uma breve pausa. Por exemplo: CONCURRENT_MODIFICATION, UNEXPECTED_INTERNAL_API_ERROR e RATE_EXCEEDED.

    No caso de solicitações iniciadas pelo usuário, é possível indicar imediatamente um erro na sua IU e oferecer uma opção para o usuário realizar uma nova tentativa. Como alternativa, seu aplicativo pode repetir automaticamente a solicitação primeiro e exibir o erro na IU somente depois de um número máximo de tentativas ou tempo de espera total do usuário.

    No caso de solicitações iniciadas pelo back-end, seu aplicativo repetirá automaticamente a solicitação até um número máximo de tentativas.

    Ao repetir solicitações, use uma política de backoff exponencial. Por exemplo, se você pausar 5 segundos antes da primeira tentativa, poderá pausar 10 segundos após a segunda e 20 segundos após a terceira, O backoff exponencial ajuda a garantir que você não esteja chamando a API de maneira muito agressiva.

    No caso de erros de RATE_EXCEEDED, o tempo que seu aplicativo é pausado antes de fazer uma nova tentativa deve ser, pelo menos, maior que o campo retryAfterSeconds no erro. Para mais detalhes, consulte o guia de limites de taxa. Alguns erros que permitem uma nova tentativa podem ser repetidos com antecedência. Porém, eles devem obedecer à política de backoff exponencial.

  3. Erros de validação

    Erros de validação indicam que a entrada de uma operação não foi aceitável. Por exemplo: PolicyViolationError, DateError, DateRangeError, StringLengthError, UrlError, entre outros.

    Os erros de validação são mais comuns em solicitações iniciadas pelo usuário, quando ele insere uma entrada inválida. Nesses casos, você deve fornecer uma mensagem de erro adequada ao usuário, com base no erro específico de API que ocorreu. Também é possível validar a entrada do usuário para erros comuns antes de fazer uma chamada de API, tornando seu aplicativo mais responsivo, e o uso da sua API, mais eficiente.

    No caso de solicitações iniciadas pelo back-end, seu aplicativo poderá adicionar a operação com falha a uma fila para a revisão de um operador humano.

  4. Erros relacionados à sincronização

    Muitos apps do AdWords possuem um banco de dados local para armazenar os objetos do Google AdWords deles. Um desafio dessa abordagem é a possível falta de sincronia entre o banco de dados local e os objetos reais no Google AdWords. Por exemplo, um usuário pode excluir um grupo de anúncios diretamente no Google AdWords, mas o aplicativo e o banco de dados local não terão conhecimento sobre a alteração e enviarão chamadas de API como se o grupo de anúncios existisse. Esses problemas de sincronização podem se manifestar por meio de uma variedade de erros, como INVALID_ID, DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, entre outros.

    No caso de solicitações iniciadas pelo usuário, uma estratégia possível é alertar o usuário sobre um possível problema de sincronização, iniciar imediatamente uma tarefa que recupere a classe relevante de objetos do Google AdWords e atualize o banco de dados local e, em seguida, solicitar que o usuário atualize a IU.

    No caso de solicitações iniciadas pelo back-end, alguns erros fornecem informações suficientes para que seu aplicativo corrija o banco de dados local de forma automática e gradual. Por exemplo, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD fará com que seu aplicativo marque esse anúncio como "Removido" no banco de dados local. Caso não seja possível tratar um erro dessa forma, seu aplicativo poderá iniciar uma tarefa mais completa de sincronização ou ser adicionado a uma fila para a revisão de um operador humano.

Lidar com falhas parciais

Por padrão, as solicitações à API são atômicas: se um erro ocorrer durante apenas uma operação na solicitação, todas as operações serão canceladas. A atomicidade é um padrão seguro, mas indesejável em muitos casos, já que as operações podem ser independentes, e apenas as com falha precisem ser revisadas. Há duas estratégias para lidar com esse comportamento padrão.

A primeira estratégia é revisar os erros na resposta, correlacioná-los às operações que geraram os erros e enviar uma nova solicitação apenas com as operações que não geraram erros. Após isso, as operações devem ser concluídas com êxito. Também é possível transferir as operações que geraram erros ao seu mecanismo de tratamento de erros (veja acima) ou enviá-las para a revisão de um operador humano.

A segunda estratégia é ativar a sinalização de falhas parciais nas suas solicitações da Google AdWords API. Ao ativá-la, cada operação será tratada de maneira independente. Se uma delas apresentar um erro, as outras não serão afetadas. Os erros em operações específicas ainda serão retornados normalmente. Todas as nossas bibliotecas cliente são compatíveis com essa sinalização.

As principais vantagens de usar a sinalização de falhas parciais são a simplicidade e o número menor de chamadas da API, já que as operações válidas são aplicadas automaticamente, sem que você precise repeti-las. Na maioria dos aplicativos, a falha parcial é adequada.

No entanto, em alguns aplicativos, é mais útil ter mais controle sobre o tratamento de erros. Por exemplo, suponha que um aplicativo não queira que os erros de política de um anúncio afetem os outros anúncios. No entanto, ele deseja que outros erros, como aqueles que sinalizam problemas maiores, cancelem a solicitação inteira. Para implementar essa ideia, o aplicativo deve empregar a primeira estratégia acima.

Em ambos os casos, alguns erros podem refletir uma dependência entre operações que seriam válidas por conta própria. Por exemplo: AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPS e AdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES.

Sincronizar back-ends

Caso os usuários do seu aplicativo tenham acesso manual às contas do Google AdWords, eles podem fazer alterações sem o conhecimento do seu aplicativo. Isso causará uma falta de sincronia no banco de dados local do seu aplicativo. Conforme mencionado acima, você pode solucionar os erros relacionados à sincronização de forma reativa. Porém, também é possível evitá-los de forma proativa. Uma estratégia proativa é executar uma tarefa de sincronização durante a noite em todas as suas contas, recuperando os objetos do Google AdWords nelas e fazendo comparações com seu banco de dados local. Para que a recuperação seja eficiente, considere usar relatórios de estrutura em vez de serviços normais da API.

Registrar erros

Todos os erros devem ser registrados para facilitar a depuração e o monitoramento. No mínimo, registre o código da solicitação, as operações que causaram o erro e o erro em si. Outras informações para o registro são: ID de cliente, serviço de API, latência da solicitação de ida e volta, número de tentativas e solicitação e resposta brutas do SOAP.

As bibliotecas cliente oferecem recursos integrados de registro de SOAP, bem como a possibilidade de recuperar o cabeçalho requestId.

Lembre-se de monitorar as tendências em erros da API para detectar e lidar com os problemas no seu aplicativo. Considere criar sua própria solução ou empregar uma das diversas ferramentas comerciais disponíveis que podem usar seus registros para produzir painéis interativos e enviar alertas automatizados.

Diversos

Usar contas de teste

Contas de teste são contas do Google AdWords que não veiculam anúncios. Você pode usar uma conta de teste para fazer experiências com a Google AdWords API e verificar se a conectividade, a lógica de gerenciamento de campanhas ou outros processos do seu aplicativo estão funcionando conforme o esperado. Seu token de desenvolvedor não precisa ser aprovado para usá-lo em uma conta de teste. Portanto, você pode começar a desenvolver imediatamente com a Google AdWords API depois que solicitar um token de desenvolvedor, antes mesmo do seu aplicativo ser revisado.

Ideias de segmentação em lote

Ao gerar ideias de segmentação usando TargetingIdeaService, TargetingIdeaSelector aceita um RequestType de IDEAS ou STATS. As solicitações de STATS podem ser usadas para recuperar estatísticas de palavras-chave conhecidas. Para recuperar estatísticas de várias palavras-chave, combine-as em uma única solicitação. Para isso, liste-as em RelatedToQuerySearchParameter. Uma TargetingIdea será retornada para cada palavra-chave. Isso é mais eficiente do que fazer uma solicitação diferente para cada palavra-chave.

Enviar comentários sobre…

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