Vídeo: Confira a palestra sobre serviços e recursos do workshop de 2019
Este guia apresenta os principais componentes da API Google Ads. A API Google Ads 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.
O recurso de nível superior de uma conta é o cliente.
Cada cliente tem uma ou mais campanhas ativas.
Cada campanha contém um ou mais grupos de anúncios, usados para organizar seus anúncios em coleções lógicas.
O anúncio do grupo de anúncios representa um anúncio que você está exibindo. Com exceção das campanhas para apps, que podem ter somente 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.
Existem muitos tipos de critério, como palavras-chave, faixas etárias e locais. Os critérios definidos no nível da campanha afetam todos os outros recursos 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, campanha ou grupo de anúncios. Com as extensões, você pode fornecer mais informações 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
Cada objeto no Google Ads é identificado pelo seu próprio ID. 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 de 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, anúncio de hotel ou anúncio local. Esse valor pode ser acessado no campo
AdGroupAd.ad.type
e retorna um valor no tipo enumerado
AdType
.
Nomes de recursos
Cada recurso é identificado exclusivamente por uma string resource_name
, que
concatena o recurso e os pais em um caminho. Por exemplo, os nomes dos recursos de campanhas têm o seguinte formato:
customers/customer_id/campaigns/campaign_id
Portanto, em uma campanha com o ID 987654
na conta do Google Ads com o ID de cliente 1234567
, o resource_name
seria:
customers/1234567/campaigns/987654
Serviços
Com os serviços, você pode recuperar e modificar suas entidades do Google Ads. Existem três tipos de serviços: modificação, recuperação de objetos e estatísticas e de metadados.
Modificar objetos (mutate)
Esses serviços modificam as 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:
CustomerService
para modificar clientes.CampaignService
para modificar campanhas.AdGroupService
para modificar grupos de anúncios.
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 uma discussão detalhada sobre as 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 você tiver vários usuários atualizando o mesmo objeto com seu aplicativo ou se estiver modificando objetos do Google Ads em paralelo usando várias linhas de execução. Isso inclui a atualização do objeto em várias conversas no mesmo aplicativo ou em aplicativos diferentes (por exemplo, seu app e uma sessão simultânea de IU do Google Ads).
A API não oferece uma maneira de bloquear um objeto antes da atualização. Se duas origens
tentarem modificar simultaneamente um objeto, a API vai gerar uma
DatabaseError.CONCURRENT_MODIFICATION_ERROR
.
Modificações assíncronas vs. síncronas
Os métodos mutate 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 a resposta de cada solicitação. Essa abordagem é relativamente simples de codificar, mas ela poderá 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 pela conclusão. Depois que uma tarefa em lote é enviada, os servidores da Google Ads API executam operações de forma assíncrona, liberando os processos para executar outras operações. É possível verificar periodicamente o status do job até a 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 mutação pode ser validada sem realmente executar a chamada em dados reais. É possível testar a solicitação em busca de parâmetros ausentes e valores de campo incorretos sem executar a operação.
Para usar esse recurso, defina o campo booleano validate_only
opcional da solicitação como
true
. A solicitação é totalmente validada como se fosse
executada, mas a execução final é 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.
validate_only
é particularmente útil para testar anúncios para detectar violações comuns da política. Os anúncios são rejeitados automaticamente quando violam políticas, como uso de palavras específicas, pontuação, letras maiúsculas ou comprimento. Um único anúncio inadequado
pode causar a falha de um lote inteiro. O teste de 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 conferir
como isso funciona.
Acessar objetos e estatísticas de desempenho
GoogleAdsService
é o serviço único e 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 da consulta, confira o guia da linguagem de consulta do Google Ads.
Recuperar metadados
GoogleAdsFieldService
recupera metadados sobre 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.