Estrutura da API Reporting do Search Ads 360

Os principais componentes da API Search Ads 360 Reporting são recursos e serviços. Um recurso representa uma entidade do Search Ads 360, e você usa um serviço para recuperá-las.

Hierarquia de objetos

Uma conta do Search Ads 360 é 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 que agrupam seus anúncios em coleções lógicas.

  • Cada AdGroup contém um ou mais anúncios do grupo de anúncios.

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

    • Existem 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 para toda a campanha.

Recursos

Os recursos representam as entidades na sua conta do Search Ads 360. Os recursos de exemplo incluem Customer, Campaign e AdGroup.

IDs dos objetos

Cada objeto no Search Ads 360 é identificado por seu próprio código. Alguns IDs são exclusivos em nível global, ou seja, em todas as contas do Search Ads 360, enquanto outros são exclusivos apenas em um escopo limitado.

Escopo de exclusividade do ID do objeto
ID do orçamento Global
ID da campanha Global
ID do Grupo de anúncios Global
ID do anúncio Grupo de anúncios

Cada par AdGroupId / AdId é globalmente exclusivo.
AdGroupCriterion ID Grupo de anúncios

Cada par de AdGroupId / CriterionId é globalmente exclusivo.
CampaignCriterion ID Campanha

Cada par CampaignId / CriterionId é globalmente exclusivo.
Extensões de anúncio Campanha

Cada par CampaignId / AdExtensionId é globalmente exclusivo.
ID de feed Global
Feed Item ID Global
Feed Attribute ID Feed
Feed Mapping ID Global
ID do rótulo Global
ID da lista de usuários Global

Essas regras de ID podem ser úteis ao projetar o armazenamento local para seus objetos do Search Ads 360.

Tipos de objeto

Alguns objetos podem ser usados para vários tipos de entidade. Nesse caso, o objeto contém um campo type que descreve o conteúdo. Por exemplo, AdGroupAd pode se referir a um anúncio de texto, de hotel ou local. É possível acessar o valor do tipo pelo campo AdGroupAd.ad.type. O valor é retornado 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.

Os nomes dos recursos da campanha, por exemplo, têm o seguinte formato:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Uma campanha com o ID 987654 na conta do Search Ads 360 com o ID de cliente 1234567 tem o resource_name:

customers/1234567/campaigns/987654

Serviços

Com os serviços, você pode recuperar as entidades e os metadados do Search Ads 360. Há três tipos de serviço:

SearchService
SearchAds360Service é o serviço unificado para recuperar todos os objetos de recursos e estatísticas de desempenho. Ele oferece dois métodos: Search e SearchStream. Ambos os métodos exigem uma consulta que especifique o recurso a ser consultado, os atributos do recurso e as métricas de desempenho 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 desempenho. Consulte Criar relatórios de pesquisa e Linguagem de consulta do Search Ads 360 para mais informações.
Serviço de campo
SearchAds360FieldService recupera metadados sobre recursos, como os atributos disponíveis para um recurso e o tipo de dados. É possível solicitar o catálogo de recursos, campos de recursos, chaves de segmentação e métricas disponíveis nos métodos de pesquisa SearchAds360Service. Consulte Extrair metadados de recursos para saber mais.
Serviços específicos da entidade

Esses serviços fornecem um método de solicitação GET que recupera uma única instância de recurso. Isso é útil para examinar a estrutura de um recurso.

Confira alguns exemplos de serviços específicos da entidade: