Como trabalhar com objetos

Um caso de uso comum da Google AdWords API é gerenciar campanhas na conta do Google AdWords. Este guia mostrará a você os objetos fundamentais do Google AdWords (como Campaigns, AdGroups etc.) que são necessários para gerenciamento de campanhas, além de informações de como eles estão relacionados entre si e como trabalhar com eles.

Recomendamos que você aperfeiçoe seu conhecimento sobre o Google AdWords como uma plataforma de publicidade e os conceitos básicos sobre como a Google AdWords API funciona antes de ler este guia. Os exemplos de código deste guia usam a biblioteca Java da Google AdWords API. Se estiver procurando uma biblioteca cliente em outra linguagem de programação, consulte nossa lista completa de bibliotecas cliente. Além disso, o uso de uma biblioteca cliente é recomendado, mas opcional. Você pode usar qualquer kit SOAP na linguagem de programação de sua escolha para fazer chamadas para a API.

  1. Como os objetos do Google AdWords funcionam
  2. Serviços de gerenciamento de campanhas da Google AdWords API
    1. Método "get"
    2. Método "query"
    3. Método "mutate"
    4. Campo "operator"
    5. Como lidar com mutates simultâneos
    6. Mutates assíncronos x mutates síncronos
    7. Validação das suas chamadas mutate
  3. Próxima etapa

Como os objetos do Google AdWords funcionam

Toda conta do Google AdWords pode ser visualizada como uma hierarquia de objetos. Em cada conta, há objetos Campaigns que representam campanhas de publicidade que você está exibindo. Cada campanha possui vários objetos AdGroups, que são usados para agrupar seus anúncios em conjuntos lógicos. Cada AdGroup possui vários AdGroupAds e AdGroupCriteria. O AdGroupAd representa um anúncio que você está exibindo, e o AdGroupCriterion representa um critério (por exemplo, palavra-chave) que define como os anúncios são acionados. Você pode definir critérios no nível da campanha que definem regras para toda a campanha sobre como os anúncios são acionados. Por fim, há extensões de anúncio no nível da campanha que permitem que você forneça informações adicionais, como número de telefone, endereço físico, entre outras, em seus anúncios.

Cada objeto do Google AdWords é identificado por seu próprio código. Alguns desses códigos são exclusivos em nível global, enquanto outros são exclusivos apenas dentro de um determinado escopo (por exemplo, não em nível global). Essa exclusividade de cada código de objeto no Google é listada abaixo.

Código do objeto Escopo de exclusividade Exclusivo globalmente?
Código da campanha Global Sim
Código do grupo de anúncios Global Sim
ID do anúncio Dentro de um grupo de anúncios. Não. O par (AdGroupId, AdId) é globalmente exclusivo.
Código do AdGroupCriterion Dentro de um grupo de anúncios. Não. O par (AdGroupId, CriterionId) é globalmente exclusivo.
Código do CampaignCriterion Dentro de uma campanha. Não. O par (CampaignId, CriterionId) é globalmente exclusivo.
Extensões de anúncio Dentro de uma campanha. Não. O par (CampaignId, AdExtensionId) é globalmente exclusivo.
Código do feed Global Sim
Código do item do feed Global Sim
Código do atributo do feed Dentro de um feed. Não
Código de mapeamento do feed Global Sim

As regras de código acima podem ser úteis para designar um banco de dados local para armazenar seus objetos do Google AdWords.

Se um objeto for derivado de outro tipo, então, ele também terá um campo Type. Por exemplo, TextAd tem um campo Type para indicar o tipo do objeto, já que TextAd é derivado do objeto Ad. Se você usa uma linguagem dinâmica, pode usar esse campo para verificar se um objeto pertence a um determinado tipo (por exemplo, verifique se um objeto Ad é do tipo TextAd).

Serviços de gerenciamento de campanhas da Google AdWords API

A Google AdWords API fornece serviços de gerenciamento de campanhas para gerenciar os objetos do Google AdWords expostos. Por exemplo, CampaignService gerencia "Campaigns", AdGroupService gerencia "AdGroups", e assim por diante. Todos os serviços de gerenciamento de campanhas expõem dois métodos padrão: get e mutate.

Método "get"

Como o nome já diz, get é usado para recuperar objetos do Google AdWords. Por exemplo, você pode usar CampaignService.get para recuperar a lista de campanhas.

Cada método get usa um Seletor como entrada e retorna uma Página como resultado. A Google AdWords API não retorna todos os campos de um objeto por padrão. É necessário especificar a lista de campos que você deseja recuperar ao criar um seletor. Você pode usar predicates para filtrar seus resultados, ordering para organizar seus resultados e dateRange para limitar o período para o qual você está recuperando os resultados. Você também precisa especificar paging se estiver extraindo muitos objetos, já que a Google AdWords API acionará um erro SizeLimitError.RESPONSE_SIZE_LIMIT_EXCEEDED se você tentar extrair vários objetos sem paging. O snippet de código a seguir mostra os conceitos acima em ação, onde recuperamos e exibimos todas as campanhas em uma conta.

final int PAGE_SIZE = 100;
int offset = 0;

// Criar seletor.
Selector selector = new Selector();
selector.setFields(new String[] {"Id", "Name"});
selector.setOrdering(new OrderBy[] {new OrderBy("Name", SortOrder.ASCENDING)});
selector.setPaging(new Paging(offset, PAGE_SIZE));

CampaignPage page = null;

do {
  // Ver todas as campanhas.
  page = campaignService.get(selector);

  // Exibir campanhas.
  if (page.getEntries() != null) {
    for (Campaign campaign : page.getEntries()) {
      System.out.println("Campaign with name \"" + campaign.getName() +
          "\" and id \"" + campaign.getId() + "\" was found.");
    }
  } else {
    System.out.println("No campaigns were found.");
  }

  offset += PAGE_SIZE;
  selector.getPaging().setStartIndex(offset);
} while (offset < page.getTotalNumEntries());

Saiba mais sobre seletores e seus comportamentos nesta postagem de blog ou neste vídeo. Caso você precise procurar rapidamente campos de seletores disponíveis para diferentes serviços, consulte este guia sobre os campos do seletor.

A distribuição de nossa biblioteca cliente inclui exemplos de códigos para métodos "get" de todos os métodos de gerenciamento de campanhas. Por exemplo, você pode encontrar os exemplos de biblioteca cliente Java para os serviços de gerenciamento de campanhas nas pastas basicoperations e campaignmanagement da seção de exemplos de código.

Método "query"

O método query é uma alternativa ao método get que não usa seletores, mas sim um idioma como SQL chamado AWQL. O método query é suportado pelos serviços mais comuns, embora ainda haja alguns em que seja necessário usar o método get. O AWQL não suporta dados do mutate.

Para mostrar a eficiência do AWQL, considere o exemplo acima. Em vez de gastar quatro linhas escrevendo o seletor, você poderia escrever uma única string com todas as informações iguais.

String awql = "SELECT Id, Name ORDER BY Name ASC LIMIT " + offset + "," + PAGE_SIZE;

Não existe uma cláusula "FROM". Isso ocorre porque o serviço cujo método query que você está usando já define o local de onde você está selecionando. O AWQL só suporta a cláusula "FROM" quando utilizado para relatórios. Para usar essa string, você simplificaria a chamada do método query do serviço.

page = campaignService.query(awql);

Os resultados dessa chamada são os mesmos da chamada do get do exemplo acima. Em geral, essa pode ser uma forma simples e intuitiva de escrever as mesmas solicitações que você faria com uma chamada get. Use o método que você achar mais fácil. Ambos são fornecidos para sua conveniência. Para ver mais informações sobre o uso e a gramática do AWQL, consulte este guia.

Método "mutate"

Como o nome mesmo indica, o método mutate é usado para modificar (criar, atualizar ou excluir) um objeto do Google AdWords. Por exemplo, CampaignService.mutate modifica um objeto Campaign.

Para modificar qualquer objeto, você precisa criar um objeto Operation apropriado. Por exemplo, você precisa criar um CampaignOperation para modificar um objeto Campaign. O campo operator define o tipo de operação que você deseja executar (ADD, SET, REMOVE), e o campo "operand" retém o objeto que você deseja modificar. Por exemplo, o snippet de código para adicionar uma campanha é fornecido abaixo:

// Criar campanha.
Campaign campaign = new Campaign();
campaign.setName("Interplanetary Cruise #" + System.currentTimeMillis());
campaign.setStatus(CampaignStatus.PAUSED);
campaign.setBiddingStrategy(new ManualCPC());

// Você pode fornecer esses campos como opção.
campaign.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"));
campaign.setStartDate(new DateTime().plusDays(30).toString("yyyyMMdd"));
campaign.setAdServingOptimizationStatus(AdServingOptimizationStatus.ROTATE);
campaign.setFrequencyCap(new FrequencyCap(5L, TimeUnit.DAY, Level.ADGROUP));

// Somente budgetId deve ser enviado. Todos os outros campos serão ignorados por CampaignService.
// Você pode usar o BudgetService para criar um orçamento compartilhado.
Budget budget = new Budget();
budget.setBudgetId(budgetId);
campaign.setBudget(budget);

// Defina as opções de rede da campanha para Pesquisa e Rede de Pesquisa.
NetworkSetting networkSetting = new NetworkSetting();
networkSetting.setTargetGoogleSearch(true);
networkSetting.setTargetSearchNetwork(true);
networkSetting.setTargetContentNetwork(false);
networkSetting.setTargetPartnerSearchNetwork(false);
campaign.setNetworkSetting(networkSetting);

GeoTargetTypeSetting geoTarget = new GeoTargetTypeSetting();
geoTarget.setPositiveGeoTargetType(GeoTargetTypeSettingPositiveGeoTargetType.DONT_CARE);
KeywordMatchSetting keywordMatch = new KeywordMatchSetting();
keywordMatch.setOptIn(Boolean.FALSE);

TargetRestrictSetting targetRestrict = new TargetRestrictSetting();
targetRestrict.setUseAdGroup(Boolean.TRUE);
campaign.setSettings(new Setting[] {geoTarget, keywordMatch, targetRestrict});

// Criar operações.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.ADD);

CampaignOperation[] operations = new CampaignOperation[] {operation};

// Adicionar campanhas.
CampaignReturnValue result = campaignService.mutate(operations);

// Exibir campanhas.
for (Campaign campaignResult : result.getValue()) {
   System.out.println("Campaign with name \"" + campaignResult.getName()
       + "\" and id \"" + campaignResult.getId() + "\" was added.");
}

A distribuição de nossa biblioteca cliente inclui exemplos de código para o método mutate de todos os serviços de gerenciamento de campanha. Por exemplo, você pode encontrar os exemplos de biblioteca cliente Java para os serviços de gerenciamento de campanhas nas pastas basicoperations e campaignmanagement da seção de exemplos de código.

Uma questão comum associada a objetos de modificação está relacionada ao número de objetos de um determinado tipo que a conta do Google AdWords pode reter. Os limites para vários tipos de objeto do Google AdWords são listados neste artigo da Central de Ajuda. No entanto, você deve usar esse limite somente como uma orientação ao planejar suas campanhas e não deve incorporar esse código em sua aplicação.

Outro ponto importante ao modificar chamadas é que é melhor enviar várias operações por solicitação do que enviar várias solicitações com uma operação por solicitação, já que isso reduz o número de ciclos completos do servidor, aumentando assim o desempenho de seu aplicativo. Você deve também tentar agrupar suas solicitações por operações de uma entidade pai específica para aumentar o desempenho. Por exemplo, se você estiver adicionando anúncios, tente agrupar suas solicitações para adicionar anúncios a um grupo de anúncios de uma só vez, em vez de fazer uma única solicitação para adicionar anúncios a vários grupos de anúncios. Você pode ler mais sobre isso em nosso guia de práticas recomendadas.

Campo "operator"

Como discutido anteriormente, com o método mutate, o campo operator informa à Google AdWords API a natureza da operação mutate que você deseja executar: ADD, SET ou REMOVE. Como o nome implica, ADD (adicionar) serve para criar um novo objeto, SET (configurar) serve para atualizar um objeto existente e REMOVE (remover) serve para remover um objeto existente. No entanto, dependendo de como o Google AdWords gerencia um determinado tipo de objeto, alguns operadores podem não ser aplicáveis a alguns serviços.

Por exemplo, uma campanha do Google AdWords não pode ser excluída permanentemente depois de criada. Você pode apenas marcar uma campanha como excluída e pode reverter isso marcando-a como pausada ou ativa. Sendo assim, a Google AdWords API não suporta o operador "REMOVE" em "CampaignService". É necessário atualizar "Campaign" alterando seus status para "DELETED" usando o operador "SET". De forma semelhante, não é possível definir (SET) um destino de campanha, você pode somente adicionar (ADD) ou remover (REMOVE) destinos. Mais detalhes sobre como o Google AdWords trata diferentes objetos são exibidos abaixo:

Tipo Recém-adicionado Ativar / ativo Pausado Excluir / desativado
Campaign ação: mutate
operação: ADD
status: ACTIVE
ação: mutate
operação: SET
status: ACTIVE
ação: mutate
operação: SET
status: PAUSED
ação: mutate
operação: SET
status: DELETED
AdGroup ação: mutate
operação: ADD
status: ENABLED
ação: mutate
operação: SET
status: ENABLED
ação: mutate
operação: SET
status: PAUSED
ação: mutate
operação: SET
status: DELETED
AdGroupAd ação: mutate
operação: ADD
status: ENABLED
ação: mutate
operação: SET
status: ENABLED
ação: mutate
operação: SET
status: PAUSED
ação: mutate
operação: REMOVE
status: DISABLED
BiddableAdGroupCriterion ação: mutate
operação: ADD
status: ACTIVE
ação: mutate
operação: SET
status: ACTIVE
ação: mutate
operação: SET
status: PAUSED
ação: mutate
operação: REMOVE
status: DELETED
CampaignAdExtension ação: mutate
operação: ADD
status: ACTIVE
N/D N/D ação: mutate
operação: SET
status: DELETED
UserList ação: mutate
operação: ADD
status: OPEN
N/D N/D ação: mutate
operação: SET
status: CLOSED
Experiência ação: mutate
operação: ADD
status: ACTIVE
N/D N/D ação: mutate
operação: SET
status: DELETED

Como lidar com mutates simultâneos

Ao criar uma aplicação da Google AdWords API, você geralmente modificará objetos do Google AdWords paralelamente, como quando usa várias sequências para conseguir um resultado melhor para sua aplicação ou talvez haja vários usuários atualizando o mesmo objeto por meio da sua aplicação. Por isso, é importante entender como o Google AdWords lida com solicitações "mutate" simultâneas para o mesmo objeto e desenvolver sua aplicação de forma adequada.

A regra geral da modificação de um objeto do Google AdWords é que você não pode modificar o mesmo objeto de forma simultânea. Isso inclui a atualização do objeto de várias sequências na mesma aplicação ou em aplicações diferentes (por exemplo, sua aplicação e uma sessão simultânea do AdWords Editor). A Google AdWords API não oferece uma forma de bloquear um objeto antes da atualização, em vez disso, ela fornece uma abordagem otimista para o bloqueio de objetos. Se a Google AdWords API detectar que um objeto está sendo atualizado simultaneamente por mais de uma origem, ela acionará um erro CONCURRENT_MODIFICATION_ERROR. Saiba mais sobre o gerenciamento simultâneo da Google AdWords API nesta postagem do blog.

Mutates assíncronos x mutates síncronos

Os métodos mutate da Google AdWords API são síncronos, o que significa que você faz uma chamada da API, e a chamada será retornada somente depois que os objetos forem modificados ou depois que a chamada falhar. Embora essa abordagem seja relativamente simples de codificar, você também precisará se preocupar com vários outros elementos, como equilíbrio de carga, desperdício de recursos enquanto as máquinas esperam a conclusão da chamada da API etc.

Uma abordagem alternativa a isso é modificar os objetos de forma assíncrona usando MutateJobService. Ao usar MutateJobService, você pode criar tarefas que consistem em operações e lotes potencialmente grandes. Quando a tarefa for enviada, os servidores da API executarão as tarefas de forma assíncrona. Isso libera sua máquina para executar outras operações e verificar periodicamente o status para conclusão da tarefa. Outro benefício de usar APIs assíncronas é que elas incorrem somente 50% do custo de chamadas síncronas da API. Veja mais sobre APIs assíncronas neste vídeo ou no guia de processamento em lote.

Validação das suas chamadas mutate

O cabeçalho SOAP validateOnly permite que você teste suas chamadas da API, sem ter que alterar os dados. Convém localizar parâmetros ausentes e valores de campo incorretos. Para usar esse recurso, defina o campo validateOnly do RequestHeader para true. As bibliotecas cliente definem para false como padrão.

Quando substituído por true, sua solicitação será totalmente validada como se fosse ser executada, mas a execução final será ignorada. Uma resposta vazia será retornada se não houver erros. Se a validação falhar, as mensagens de erro serão retornadas informando sobre o que falhou.

Veja um exemplo de como configurar validateOnly usando nossa biblioteca Java.

Credential oAuth2Credential = new OfflineCredentials.Builder()
    .forApi(Api.ADWORDS)
    .fromFile()
    .build()
    .generateCredential();

AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

session.setValidateOnly(true);

Todas as chamadas da API feitas usando essa sessão agora terão o cabeçalho validateOnly definido para "true".

O cabeçalho validateOnly é particularmente útil para verificar violações comuns de política dos anúncios. Às vezes, os anúncios podem ser automaticamente rejeitados se falharem quanto a determinados critérios, como usar determinadas palavras, pontuações, durações ou letras maiúsculas indevidamente. Se você tentar fazer o upload de anúncios em lotes, e houver um anúncio com problema, ele poderá causar a falha de todo o lote. Testar um novo anúncio com validateOnly permite que veja facilmente quais anúncios poderiam ser rejeitados. Consulte este exemplo de código para ver essa aplicação em ação.

Mesmo sem usar a biblioteca cliente, tudo o que você precisa é configurar o cabeçalho SOAP correto, e ainda poderá validar suas solicitações mutate.

Próxima etapa

Agora você já está pronto para tentar fazer sua primeira solicitação.

Enviar comentários sobre…

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