Estrutura da API

ondemand_video Vídeo: Confira a palestra sobre serviços e recursos do workshop de 2019 (em inglês)

Este guia apresenta os principais componentes da API Google Ads. A A API Google Ads consiste em recursos e serviços. Um recurso representa uma campanha do Google Ads entidade, 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 cliente.

• Cada cliente contém um ou mais grupos campanhas.

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

• Um anúncio do grupo de anúncios representa um anúncio que você em execução. Exceto em campanhas para apps, que só podem ter um anúncio de grupo por anúncio grupo de anúncios, cada grupo terá um ou mais anúncios de grupo de anúncios.

Você pode 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.

Existem muitos tipos de critério, como palavras-chave, faixas etárias e locais. Critérios definidos na campanha afetam todos os outros recursos da campanha. Também é possível especificar orçamentos e datas de toda a campanha.

Por fim, você pode anexar extensões ao no nível da conta, da campanha ou do grupo de anúncios. As extensões permitem que você forneça informações aos 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 em em um escopo restrito.

Essas regras de ID podem ser úteis ao projetar armazenamento local para suas campanhas objetos.

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 pela AdGroupAd.ad.type e retorna um valor no Enumeração AdType.

Nomes de recursos

Cada recurso é identificado de forma exclusiva por uma string resource_name, que concatena o recurso e os pais em um caminho. Por exemplo, a campanha de recursos têm o formato:

customers/customer_id/campaigns/campaign_id

Então, para uma campanha com o ID 987654 na conta do Google Ads com o ID de cliente, 1234567, o resource_name será:

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 de estatísticas e de metadados serviços.

Modificar objetos (mutate)

Esses serviços modificam instâncias de um tipo de recurso associado usando um mutate solicitação. Eles também fornecem uma solicitação get que recupera um único recurso. o que pode ser útil para examinar a estrutura de um recurso.

Exemplos de serviços:

• CustomerService para modificação clientes.

• CampaignService para modificação campanhas.

• AdGroupService para modificar grupos de anúncios.

Cada solicitação mutate precisa incluir objetos operation correspondentes. Para exemplo, o método CampaignService.MutateCampaigns espera um ou mais instâncias de CampaignOperation. Consulte Como alterar e inspecionar objetos de um discussão detalhada das operações.

Modificações simultâneas

Um objeto do Google Ads não pode ser modificado simultaneamente por mais de uma origem. Isso podem causar erros se vários usuários atualizarem o mesmo objeto com seu aplicativo ou se você estiver modificando objetos do Google Ads em paralelo usando vários fios Isso inclui atualizar o objeto de várias linhas de execução no mesmo aplicativo, ou de diferentes aplicativos (por exemplo, seu aplicativo e um sessão simultânea da interface do Google Ads).

A API não fornece uma maneira de bloquear um objeto antes da atualização. se duas fontes tentar mutar 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 somente uma resposta depois que os objetos são transformados, exigindo que você aguarde a resposta para cada solicitação. Embora essa abordagem seja relativamente simples de programar, ela pode impactar negativamente o balanceamento de carga e desperdiçar recursos se os processos forem forçados a aguarde 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. Uma vez que em lote for enviada, os servidores da API Google Ads executam operações de forma assíncrona. liberando processos para executar outras operações. É possível verificar periodicamente o status do job para a conclusão.

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

Validação da modificação

A maioria das solicitações de mutação pode ser validada sem realmente executar a chamada com dados reais. Você pode testar a solicitação em busca de parâmetros ausentes e 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 então totalmente validada como se fosse ser executada, mas a execução final é ignorada. Se nenhum erro for encontrado, um valor será retornada. Se a validação falhar, as mensagens de erro na resposta serão e indicar os pontos de falha.

O recurso validate_only é útil principalmente para testar a política comum dos anúncios. e violações de conformidade. Os anúncios serão rejeitados automaticamente se violarem políticas como ter palavras específicas, pontuação, letras maiúsculas ou tamanho. Um único anúncio inadequado pode causar a falha de um lote inteiro. Testar um novo anúncio em uma validate_only da solicitação pode revelar essas violações. Consulte o exemplo de código para saber como lidar de violação da política para verificar isso em ação.

Acessar objetos e estatísticas de desempenho

O GoogleAdsService é a interface unificada 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 os atributos de recurso e as métricas de desempenho a serem recuperadas, predicados a serem usados para filtrar a solicitação e os segmentos a serem usados para e detalhar as estatísticas de desempenho. Para mais informações sobre formato de consulta, confira o guia sobre a Linguagem de consulta do Google Ads.

Recuperar metadados

GoogleAdsFieldService recupera metadados sobre recursos na Google Ads API, como os atributos disponíveis para um e o tipo de dados dele.

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