Estrutura da API

Vídeo: confira a palestra sobre serviços e recursos do workshop de 2019 (em inglês)

Este guia apresenta os principais componentes da API Google Ads. A Google Ads API consiste em recursos e serviços. Um recurso representa uma entidade do Google Ads, enquanto os serviços recuperam e manipulam entidades do Google Ads.

Hierarquia de objetos

Uma conta do Google Ads pode ser considerada uma hierarquia de objetos.

Modelo de campanha

  • O recurso de nível superior de uma conta é o cliente.

  • Cada cliente contém uma ou mais campanhas ativas.

  • Cada campanha contém um ou mais grupos de anúncios, usados para agrupar os anúncios em coleções lógicas.

  • Um anúncio do grupo de anúncios representa a publicidade que você está exibindo. Com exceção das campanhas para apps que podem ter apenas um anúncio por grupo, cada grupo contém um ou mais anúncios.

Você pode anexar um ou mais AdGroupCriterion ou CampaignCriterion a um grupo de anúncios ou uma campanha. Eles representam os critérios que definem como os anúncios são acionados.

Há muitos tipos de critérios, como palavras-chave, faixas etárias e locais. Os critérios definidos no nível da campanha afetam todos os outros recursos dentro dela. Você também pode especificar orçamentos e datas para toda a campanha.

Por fim, você pode anexar extensões no nível da conta, da campanha ou do grupo de anúncios. As extensões permitem que você forneça informações extras aos seus anúncios, como número de telefone, endereço ou promoções.

Recursos

Os recursos representam as entidades na sua conta do Google Ads. Campaign e AdGroup são dois exemplos de recursos.

IDs de objetos

Todos os objetos do Google Ads são identificados por um ID próprio. Alguns desses IDs são globalmente exclusivos em todas as contas do Google Ads, enquanto outros são exclusivos apenas dentro de um escopo restrito.

ID do objeto Escopo da exclusividade Exclusivo globalmente?
ID do orçamento Global Sim
ID da campanha Global Sim
AdGroup ID Global Sim
Ad ID Grupo de anúncios Não, mas o par (AdGroupId, AdId) é globalmente exclusivo
AdGroupCriterion ID Grupo de anúncios Não, mas o par (AdGroupId, CriterionId) é globalmente exclusivo
CampaignCriterion ID Campanha Não, mas o par (CampaignId, CriterionId) é globalmente exclusivo
Extensões de anúncio Campanha Não, mas o par (CampaignId, AdExtensionId) é globalmente exclusivo
ID de feed Global Sim
Feed Item ID Global Sim
Feed Attribute ID Feed Não
Feed Mapping ID Global Sim
Label ID Global Sim
ID da lista de usuários Global Sim

Essas regras de código podem ser úteis ao projetar o armazenamento local para seus objetos do Google Ads.

Alguns objetos podem ser usados para vários tipos de entidade. Nesses casos, o objeto contém um campo type que descreve o conteúdo. Por exemplo, AdGroupAd pode se referir a um objeto, como um anúncio de texto, de hotel ou local. Esse valor pode ser acessado no campo AdGroupAd.ad.type e retorna um valor na enumeração AdType.

Nomes de recursos

Cada recurso é identificado de maneira exclusiva por uma string resource_name, que concena o recurso e os pais a um caminho. Por exemplo, os nomes dos recursos da campanha têm o seguinte formato:

customers/customer_id/campaigns/campaign_id

Assim, para uma campanha com ID 987654 na conta do Google Ads com ID de cliente 1234567, resource_name seria:

customers/1234567/campaigns/987654

Serviços

Com os serviços, você pode recuperar e modificar suas entidades do Google Ads. Há três tipos de serviços: modificação, recuperação de objetos e estatísticas e de metadados.

Modificar (mutate) objetos

Esses serviços modificam instâncias de um tipo de recurso associado usando uma solicitação mutate. Eles também fornecem uma solicitação get que recupera uma única instância de recurso, o que pode ser útil para examinar a estrutura de um recurso.

Exemplos de serviços:

Cada solicitação mutate precisa incluir objetos operation correspondentes. Por exemplo, o método CampaignService.MutateCampaigns espera uma ou mais instâncias de CampaignOperation. Consulte Como alterar e inspecionar objetos para ver uma discussão detalhada sobre operações.

Modificações simultâneas

Um objeto do Google Ads não pode ser modificado simultaneamente por mais de uma origem. Isso poderá causar erros se houver vários usuários atualizando o mesmo objeto com seu aplicativo ou se você estiver modificando objetos do Google Ads em paralelo usando várias conversas. Isso inclui atualizar o objeto de várias conversas no mesmo aplicativo ou em aplicativos diferentes, por exemplo, seu app e uma sessão simultânea da interface do Google Ads.

A API não oferece uma maneira de bloquear um objeto antes da atualização. Se duas fontes tentarem modificar um objeto simultaneamente, a API vai gerar uma DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Modificações síncronas versus assíncronas

Os métodos de mutação da API Google Ads são síncronos. As chamadas de API retornam uma resposta somente após a modificação dos objetos, exigindo que você aguarde uma resposta para cada solicitação. Embora essa abordagem seja relativamente simples de codificar, ela pode afetar negativamente o balanceamento de carga e desperdiçar recursos se os processos forem forçados a aguardar a conclusão das chamadas.

Uma abordagem alternativa é modificar objetos de forma assíncrona usando BatchJobService, que executa lotes de operações em vários serviços sem esperar a conclusão. Depois que uma tarefa em lote é enviada, os servidores da Google Ads API executam operações de modo assíncrono, liberando os processos para realizar outras operações. É possível verificar periodicamente o status do job para conclusão.

Consulte o guia sobre processamento em lote para saber mais sobre o processamento assíncrono.

Validação da modificação

A maioria das solicitações de modificação pode ser validada sem realmente executar a chamada em dados reais. É possível testar a solicitação de parâmetros ausentes e valores de campo incorretos sem executar a operação.

Para usar esse recurso, defina o campo booleano opcional validate_only da solicitação como true. A solicitação seria totalmente validada como se fosse executada, mas a execução final seria ignorada. Se nenhum erro for encontrado, uma resposta vazia será retornada. Se a validação falhar, as mensagens de erro na resposta indicarão os pontos de falha.

O validate_only é útil principalmente para testar anúncios em busca de violações comuns da política. Os anúncios serão rejeitados automaticamente se violarem políticas, como palavras, pontuação, letras maiúsculas ou tamanho específicos. Um único anúncio inadequado pode causar a falha de um lote inteiro. Testar um novo anúncio em uma solicitação validate_only pode revelar essas violações. Consulte o exemplo de código sobre como lidar com erros de violação de política para saber como isso funciona.

Obter objetos e estatísticas de desempenho

GoogleAdsService é o serviço unificado para recuperar objetos e estatísticas de desempenho.

Todas as solicitações Search e SearchStream para GoogleAdsService exigem uma consulta que especifique o recurso a ser consultado, os atributos do recurso e as métricas de desempenho a serem recuperados, os predicados a serem usados para filtrar a solicitação e os segmentos a serem usados para detalhar ainda mais as estatísticas de desempenho. Para mais informações sobre o formato de consulta, confira o Guia de linguagem de consulta do Google Ads.

Recuperar metadados

GoogleAdsFieldService recupera metadados de recursos na API Google Ads, como os atributos disponíveis para um recurso e o tipo de dados dele.

Esse serviço fornece as informações necessárias para criar uma consulta para GoogleAdsService. Por conveniência, as informações retornadas por GoogleAdsFieldService também estão disponíveis na documentação de referência de campos.

Anterior
Informações gerais
Próxima
Relacionamentos de entidades