Segmentação

A segmentação, disponível na interface do Google Ads como um menu separado, pode ser implementada na Google Ads API apenas adicionando o campo correto a uma consulta. Por exemplo, adicionar segments.device a uma consulta resulta em um relatório com uma linha para cada combinação de dispositivo e o recurso especificado na cláusula FROM, além dos valores estatísticos (impressões, cliques, conversões etc.) divididos entre eles.

Enquanto na interface do Google Ads apenas um segmento por vez pode ser usado, com a API você pode especificar vários segmentos na mesma consulta.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Os resultados do envio dessa consulta para GoogleAdsService.SearchStream seriam parecidos com esta string JSON:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

No resultado do exemplo acima, os atributos para o primeiro e o segundo objetos, incluindo o nome do recurso, são os mesmos. As impressões são segmentadas por dispositivo e, assim, dois ou mais objetos podem ser retornados para a mesma campanha.

Cuidado: lembre-se de que a quantidade de linhas pode aumentar exponencialmente para cada campo de segmento adicional incluído na consulta do relatório.

Segmentação implícita

Cada relatório é inicialmente segmentado pelo recurso especificado na cláusula FROM. O campo resource_name do recurso na cláusula FROM é retornado e as métricas são segmentadas por ele, mesmo quando o campo resource_name não está explicitamente incluído na consulta. Por exemplo, quando você especifica ad_group como o recurso na cláusula FROM, ad_group.resource_name é retornado automaticamente e as métricas segmentam implicitamente no nível do ad_group.

Então, para esta consulta,

SELECT metrics.impressions
FROM ad_group

você receberia uma string JSON como esta:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Observe que o campo resource_name de adGroup é sempre retornado porque ad_group foi especificado como um recurso na cláusula FROM.

Campos de segmento selecionáveis

Nem todos os campos de segmento são selecionáveis para um determinado recurso na cláusula FROM. Por exemplo, vamos continuar consultando no recurso ad_group. Para que um campo de segmento possa ser selecionado no recurso ad_group, ele precisa existir na lista Segments de ad_group. A lista Segments é a parte amarela da tabela de campos disponíveis na página de metadados do recurso ad_group.

Segmentar recursos

Ao selecionar alguns recursos, você pode ter a opção de fazer a junção implícita em recursos relacionados selecionando os campos deles ao lado dos campos do recurso na cláusula FROM. Esses recursos relacionados podem ser encontrados na lista Attributed Resources do recurso na página de metadados da cláusula FROM. No caso do recurso ad_group, você verá que também é possível selecionar campos do recurso campaign. O campo resource_name de qualquer Attributed Resources com pelo menos um campo na cláusula SELECT será retornado automaticamente, mesmo quando o campo resource_name não estiver explicitamente incluído na consulta.

Assim como na seleção de campos Attributed Resource, também é possível selecionar campos Segmenting Resource. Se um determinado recurso tiver uma lista Segmenting Resources na página de metadados, a seleção de campos de um dos recursos listados fará com que a consulta seja mais segmentada pelo resource_name retornado desse Segmenting Resource. Por exemplo, você vai notar que o recurso campaign está listado como um Segmenting Resource para o recurso campaign_budget. A seleção de qualquer campo de campanha, como campaign.name, do recurso "campaign_budget" faz, não apenas faz com que o campo "campaign.name" seja retornado, mas também faz com que o campo campaign.resource_name seja retornado e segmentado.

Capacidade de seleção entre segmentos e métricas

Um determinado campo de segmento pode não ser compatível com alguns dos outros campos de segmento ou com alguns dos campos de métricas. Para identificar quais campos de segmento são compatíveis entre si, é possível analisar a lista selectable_with dos segmentos na cláusula SELECT.

No caso do recurso ad_group, há mais de 50 segmentos disponíveis que você pode selecionar. No entanto, a lista de selectable_with para segments.hotel_check_in_date é um conjunto muito menor de segmentos compatíveis. Isso significa que, se você adicionar o campo segments.hotel_check_in_date na cláusula SELECT, limitará os segmentos disponíveis que você ainda pode selecionar à interseção dessas duas listas.

Ao adicionar alguns segmentos, as métricas na linha de resumo podem diminuir

Quando segments.keyword.info.match_type é adicionado a uma consulta com FROM ad_group_ad, esse segmento instrui a consulta a buscar apenas as linhas de dados que têm palavras-chave e remover qualquer linha que não esteja associada a uma palavra-chave. Nesse caso, as métricas seriam menores porque excluiriam qualquer métrica que não seja de palavra-chave.

Regras para segmentos na cláusula WHERE

Quando um segmento está na cláusula WHERE, ele também precisa estar na cláusula SELECT. A exceção a essa regra são os seguintes segmentos de data, chamados de segmentos de data principal:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Regras para campos de segmento de data principal

Os segmentos segments.date, segments.week, segments.month, segments.quarter e segments.year funcionam da seguinte maneira:

• Esses segmentos podem ser filtrados na cláusula WHERE sem aparecer na cláusula SELECT.

• Se algum desses segmentos estiver na cláusula SELECT, um período finito composto de segmentos de data principal precisará ser especificado na cláusula WHERE. Os segmentos de data não precisam ser os mesmos especificados em SELECT.

Exemplos

Inválido:como segments.date está na cláusula SELECT, você precisa especificar um período finito na cláusula WHERE para segments.date, segments.week, segments.month, segments.quarter ou segments.year.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign
Válido:essa consulta retorna nomes de campanhas e cliques acumulados durante o período. Observe que segments.date não precisa aparecer na cláusula SELECT.	SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2020-01-01' AND segments.date < '2020-02-01'
Válido:essa consulta retorna nomes de campanhas e cliques segmentados por data para todos os dias do período.	SELECT campaign.name, metrics.clicks, segments.date FROM campaign WHERE segments.date > '2020-01-01' AND segments.date < '2020-02-01'
Válido:essa consulta retorna nomes de campanhas e cliques segmentados por mês para todos os dias do período.	SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2020-01-01' AND segments.date < '2020-02-01'
Válido:essa consulta retorna nomes de campanhas e cliques segmentados por trimestre e, depois, por mês para todos os meses do período.	SELECT campaign.name, metrics.clicks, segments.quarter, segments.month FROM campaign WHERE segments.year > 2015 AND segments.year < 2020

search_term_view

O recurso search_term_view também é implicitamente segmentado por grupo de anúncios, não apenas por um termo de pesquisa, conforme refletido pela estrutura do nome do recurso, que também inclui o grupo de anúncios. Portanto, você terá algumas linhas aparentemente duplicadas com os mesmos termos de pesquisa nos resultados quando, na verdade, elas pertencerem a um grupo de anúncios diferente:

{
  "results":[
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~2222222222~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"3"
      },
      "segments":{
        "date":"2015-06-15"
      }
    },
    {
      "searchTermView":{
        "resourceName":"customers/1234567890/searchTermViews/111111111~33333333333~Z29vZ2xlIHBob3RvcyBpb3M",
        "searchTerm":"google photos"
      },
      "metrics":{
        "impressions":"2"
      },
      "segments":{
        "date":"2015-06-15"
      }
    }
  ]
}

Embora os dois objetos retornados neste exemplo pareçam ser duplicados, os nomes dos recursos são diferentes, especialmente na parte do "grupo de anúncios". Isso significa que o termo de pesquisa "google fotos" é atribuído aos dois grupos de anúncios (ID 2222222222 e 33333333333) na mesma data (15/06/2015). Assim, podemos concluir que a API funcionou conforme o esperado e não retornou objetos duplicados nesse caso.

Importante :tecnicamente, também podemos dizer que o recurso search_term_view também é segmentado implicitamente por uma campanha. No entanto, um grupo de anúncios precisa sempre pertencer a uma campanha. Portanto, usar apenas um grupo de anúncios para eliminar as linhas de dados duplicadas é aceitável, porque um grupo de anúncios é o bloco mais básico.