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 que compõem a API Google Ads. A API Google Ads é composta por 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 conta contém uma ou mais campanhas ativas.

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

  • Cada AdGroup contém um ou mais anúncios do grupo de anúncios. Uma AdGroupAd representa um anúncio que você está exibindo.

É 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ério, como palavras-chave, faixas etárias e locais. Os critérios definidos no nível da campanha afetam todos os outros recursos dela. Também é possível especificar orçamentos e datas de toda a campanha.

Por fim, é possível anexar extensões no nível da conta, campanha ou grupo de anúncios. Com as extensões, você exibe mais informações nos 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 IDs são exclusivos globalmente 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 Yes
ID da campanha Global Yes
AdGroup ID Global Yes
Ad ID Ad Group Não, mas o par (AdGroupId, AdId) é exclusivo globalmente
AdGroupCriterion ID Ad Group Não, mas o par (AdGroupId, CriterionId) é exclusivo globalmente
CampaignCriterion ID Campaign Não, mas o par (CampaignId, CriterionId) é exclusivo globalmente
Extensões de anúncio Campaign Não, mas o par (CampaignId, AdExtensionId) é exclusivo globalmente
ID de feed Global Yes
Feed Item ID Global Yes
Feed Attribute ID Feed No
Feed Mapping ID Global Yes
Label ID Global Yes
ID da lista de usuários Global Yes

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 dele. Por exemplo, AdGroupAd pode se referir a um anúncio de texto, de hotel, de anúncio local etc. Esse valor pode ser acessado no 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 o concatena e os pais dele em um caminho. Por exemplo, os nomes dos recursos da campanha têm o formato:

customers/customer_id/campaigns/campaign_id

Assim, para uma campanha com ID 987654 na conta do Google Ads com 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ço: modificação, recuperação de objetos e estatísticas e serviços de recuperação de metadados.

Modificar objetos (mutação)

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:

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 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 de várias linhas de execução no mesmo aplicativo ou de diferentes aplicativos (por exemplo, seu aplicativo e uma sessão simultânea da IU 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 gerará uma DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Mudanças síncronas e assíncronas

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

Uma abordagem alternativa é modificar os objetos de maneira assíncrona usando o AutorizarService, que executa lotes de operações em vários serviços sem esperar pela conclusão deles. Depois que um job em lote é enviado, os servidores da API Google Ads executam 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 de modificação pode ser validada sem realmente executar a chamada em relação a dados reais. Você pode testar a solicitação para verificar se há 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 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 rejeitados automaticamente se violarem políticas como palavras, pontuação, letras maiúsculas ou duração específicas. Um único anúncio inadequado 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.

Ver estatísticas de objetos e desempenho

GoogleAdsService é o serviço unificado e 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 e métricas de desempenho a serem recuperados, os predicados a serem usados para filtrar a solicitação e os segmentos 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 informações necessárias para construir 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
Visão geral
Próxima
Relacionamentos de entidades