Vídeo: confira a palestra de serviços e recursos do workshop de 2019
Este guia apresenta os principais componentes da Google Ads API. 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 visualizada como uma hierarquia de objetos.
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, que são usados para agrupar seus anúncios em conjuntos lógicos.
Um 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 apenas um anúncio por grupo, cada grupo contém um ou mais anúncios desse tipo.
É possível 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 da campanha. Você também pode especificar datas e orçamentos para toda a campanha.
Por fim, é possível anexar extensões no nível da conta, da campanha ou do grupo de anúncios. As extensões permitem fornecer informações adicionais aos seus anúncios, como número de telefone, endereço ou promoções.
Recursos
Os recursos representam as entidades em sua conta do Google Ads.
Campaign
e AdGroup
são
dois exemplos de recursos.
IDs de objeto
Cada objeto no Google Ads é identificado por seu próprio ID. Alguns desses códigos 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 | Globalmente exclusivo? |
---|---|---|
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 ) é exclusivo globalmente |
AdGroupCriterion ID | Grupo de anúncios | Não, mas o par (AdGroupId , CriterionId ) é exclusivo globalmente |
CampaignCriterion ID | Campanha | Não, mas o par (CampaignId , CriterionId ) é exclusivo globalmente |
Extensões de anúncio | Campanha | Não, mas o par (CampaignId , AdExtensionId ) é exclusivo globalmente |
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 anúncio de texto, anúncio de hotel, anúncio local etc. Esse valor pode ser acessado por meio do campo AdGroupAd.ad.type
e retorna um valor na enumeração AdType
.
Nomes de recursos
Cada recurso é identificado exclusivamente por uma string resource_name
, que concatena o recurso e os pais dele em 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 objetos (mutate)
Esses serviços modificam instâncias de um tipo de recurso associado usando uma solicitação mutate
. Elas 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 os objetos do Google Ads em paralelo usando várias linhas de execução. Isso inclui a atualização do objeto por meio de conversas no mesmo aplicativo ou em aplicativos diferentes (por exemplo, seu aplicativo e uma sessão simultânea da IU do Google Ads).
A API não fornece uma maneira de bloquear um objeto antes da atualização. Se
duas fontes tentarem modificar um objeto simultaneamente, a API gerará um
DatabaseError.CONCURRENT_MODIFICATION_ERROR
.
Modificações síncronas e assíncronas
Os métodos de modificação da API do Google Ads são síncronos. As chamadas de API retornam uma resposta somente depois da modificação dos objetos, e você precisa aguardar uma resposta para cada solicitação. Embora essa abordagem seja relativamente simples de codificar, ela pode afetar negativamente o balanceamento de carga e os recursos de desperdício se os processos forem forçados a aguardar a conclusão das chamadas.
Uma abordagem alternativa é modificar os objetos de forma assíncrona usando BatchJobService, que executa lotes de operações em vários serviços sem aguardar a conclusão. Depois que uma tarefa em lote é enviada, os servidores da Google Ads API realizam operações de maneira assíncrona, liberando 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 mutate pode ser validada sem realmente executar a chamada em relação a dados reais. Você pode testar a solicitação em busca de parâmetros ausentes e valores de campo incorretos sem precisar 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 ser
executada, mas a execução final será 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
é especialmente útil para testar anúncios em busca de violações comuns da política. Os anúncios serão automaticamente rejeitados se violarem políticas como palavras, pontuação, letras maiúsculas ou comprimento específicos. Um único anúncio indevido pode causar falha em 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 ver 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 especifica 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
O GoogleAdsFieldService
recupera metadados sobre recursos na Google Ads API, 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 dos campos.