Estrutura da API

Este guia apresenta os principais componentes que formam 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 vista 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, usados para agrupar seus anúncios em coleções lógicas.

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

As campanhas Performance Max usam uma estrutura diferente de outros tipos de campanha: em vez de grupos de anúncios e anúncios de grupo de anúncios, uma campanha Performance Max contém grupos de recursos. Você vincula recursos do criativo a um grupo de recursos usando AssetGroupAsset e anexa indicadores de público-alvo ou tema de pesquisa usando AssetGroupSignal.

É possível anexar um ou mais AdGroupCriterion ou CampaignCriterion recursos a um grupo de anúncios ou campanha. Eles representam 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 da campanha. Também é possível especificar orçamentos, datas e horários de início e término para campanhas ou para anúncios individuais usando AdGroupAd.start_date_time e AdGroupAd.end_date_time.

Por fim, é possível anexar recursos no nível da conta, da campanha, do grupo de anúncios ou do grupo de recursos. Os recursos permitem que você forneça informações extras aos seus anúncios, como números de telefone, endereços ou promoções. Consulte Visão geral dos recursos.

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 próprio ID. Alguns desses IDs são globalmente exclusivos em todas as contas do Google Ads, enquanto outros são exclusivos apenas em um escopo limitado.

Essas regras de ID 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 responsivo de pesquisa, um anúncio de hotel ou um anúncio da Geração de Demanda. Esse valor pode ser acessado pelo campo AdGroupAd.ad.type e retorna um valor na enumeração AdType. A mutabilidade pode variar de acordo com a versão. Por exemplo, VideoResponsiveAdInfo em Ad é mutável na v24 e versões mais recentes.

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 de 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

Os serviços permitem 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 (mudar) objetos

Os serviços específicos de recursos modificam instâncias de um tipo de recurso associado usando uma solicitação mutate. Também é possível usar GoogleAdsService.Mutate para realizar mutações atômicas em vários tipos de recursos em uma única solicitação, como criar um orçamento da campanha, uma campanha e um grupo de anúncios juntos.

Exemplos de serviços específicos de recursos:

• 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 Alterar 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 você tiver vários usuários atualizando o mesmo objeto com seu app ou se estiver mudando 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 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 origens tentarem mudar um objeto simultaneamente, a API vai gerar um DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Modificações assíncronas x síncronas

Os métodos de modificação da API Google Ads são síncronos. As chamadas de API retornam uma resposta somente depois que os objetos são modificados, 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 realiza lotes de operações em vários serviços sem aguardar a conclusão. 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 saber se ele foi concluído.

Consulte o guia de processamento em lote para mais informações sobre o processamento assíncrono.

Validação da modificação

A maioria das solicitações de modificação pode ser validada sem 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 é totalmente validada como se fosse ser executada, mas a execução final é ignorada. Se nenhum erro for encontrado, a resposta será retornada sem resultados modificados preenchidos (results está vazio). Se a validação falhar, a solicitação vai falhar com um GoogleAdsFailure RPC erro por padrão (partial_failure = false) ou vai retornar uma resposta normal com erros específicos da operação em partial_failure_error quando partial_failure = true.

validate_only é particularmente ú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, pontuação, capitalização ou comprimento específicos. Um único anúncio inadequado pode fazer com que todo um lote falhe. Testar um novo anúncio em uma solicitação validate_only pode revelar essas violações. Consulte o exemplo de código para processar erros de violação da política para ver isso em ação.

Receber objetos e estatísticas de performance

GoogleAdsService é o serviço único e unificado para recuperar objetos e estatísticas de performance.

Todas as Search e SearchStream solicitações para GoogleAdsService exigem uma consulta que especifique o recurso a ser consultado, os atributos de recurso e as métricas de performance a serem recuperadas, os predicados a serem usados para filtrar a solicitação e os segmentos a serem usados para detalhar ainda mais as estatísticas de performance. 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. Consulte o guia de metadados de recursos para detalhes sobre como consultar esse serviço.

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