Estrutura da API

Vídeo: confira a palestra sobre serviços e recursos do workshop de 2019

Este guia apresenta os principais componentes que compõem a 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 agrupar os anúncios em coleções lógicas.

• Um anúncio de grupo de anúncios representa um anúncio que você está veiculando. Exceto em campanhas para apps, que podem ter apenas um anúncio por grupo, cada grupo de anúncios contém um ou mais anúncios.

É possível anexar um ou mais AdGroupCriterion ou CampaignCriterion a um grupo de anúncios ou campanha. Eles representam os critérios que definem como os anúncios são acionados.

Há 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 da campanha. Também é possível 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. 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 dos objetos

Cada objeto no Google Ads é identificado pelo próprio ID. Alguns desses IDs são exclusivos globalmente em todas as contas do Google Ads, enquanto outros são exclusivos apenas em um escopo limitado.

ID do objeto	Escopo da exclusividade	Exclusivo globalmente?
ID do orçamento	Global	Sim
Campaign ID	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 identificação 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 pelo 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 campanha têm o formato:

customers/customer_id/campaigns/campaign_id

Portanto, para 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. Há três tipos de serviços: modificação, recuperação de objetos e estatísticas e recuperação de metadados.

Modificar (mutar) 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.

Importante: as solicitações de get são limitadas a 1.000 por dia. Para a maioria dos casos de uso reais, solicite relatórios usando GoogleAdsService.

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 operações.

Modificações simultâneas

Um objeto do Google Ads não pode ser modificado simultaneamente por mais de uma origem. Isso pode causar erros se vários usuários estiverem atualizando o mesmo objeto com seu app ou se você estiver modificando objetos do Google Ads em paralelo usando várias linhas de execução. Isso inclui atualizar o objeto de várias linhas de execução no mesmo aplicativo ou de diferentes aplicativos (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 transformar um objeto simultaneamente, a API vai gerar uma DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mutações assíncronas e síncronas

Os métodos de mutação da API Google Ads são síncronos. As chamadas de API só retornam uma resposta depois que os objetos são modificados, exigindo que você aguarde uma resposta para cada solicitação. Embora essa abordagem seja relativamente simples de programar, 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 é mudar objetos de forma assíncrona usando BatchJobService, que executa lotes de operações em vários serviços sem aguardar a conclusão deles. Depois que um job em lote é enviado, os servidores da API Google Ads executam operações de forma assíncrona, liberando processos para realizar outras operações. É possível verificar periodicamente o status do job para conferir a conclusão.

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

Validação da modificação

A maioria das solicitações de mutação pode ser validada sem executar a chamada em dados reais. É possível testar a solicitação para 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 seria totalmente validada como se fosse ser 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 vão indicar os pontos de falha.

O validate_only é especialmente útil para testar anúncios em busca de violações comuns de políticas. Os anúncios são rejeitados automaticamente se violarem políticas, como ter palavras específicas, pontuação, letras maiúsculas ou comprimento. Um único anúncio inválido 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 para como lidar com erros de violação de política e conferir isso em ação.

Conferir objetos e estatísticas de performance

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

Todas as solicitações de 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 as estatísticas de desempenho. Para mais informações sobre o formato da consulta, consulte 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. Para sua comodidade, as informações retornadas por GoogleAdsFieldService também estão disponíveis na documentação de referência dos campos.