Transferências do Google Ads

Com o serviço de transferência de dados do BigQuery para Google Ads (antes conhecido como Google AdWords), é possível programar e gerenciar automaticamente jobs de carregamento recorrentes dos dados de relatórios do Google Ads.

Relatórios compatíveis

O serviço de transferência de dados do BigQuery para Google Ads é compatível com a API Google Ads v14:

Para informações sobre como os relatórios do Google Ads são transformados em tabelas e visualizações do serviço de transferência de dados do BigQuery, consulte Transformações de relatórios do Google Ads.

Para mapear os relatórios do Google Ads para a IU do Google Ads, consulte Como mapear relatórios para a IU do Google Ads.

Opção de relatório Suporte
Versão da API compatível

v14
Programação

Diariamente, no horário em que a transferência foi criada pela primeira vez (padrão)

Você pode configurar a hora do dia.
Janela de atualização

Últimos 7 dias (padrão)

Configurável para até 30 dias

Snapshots de tabelas de correspondência são produzidos uma vez por dia e armazenados na partição referente à data de execução mais recente. Esses snapshots NÃO são atualizados quanto a preenchimentos ou dias carregados por meio da janela de atualização.
Duração máxima do preenchimento

Sem limite

O Google Ads não tem limites conhecidos de retenção de dados, exceto o Relatório de desempenho de cliques, mas o serviço de transferência de dados do BigQuery tem limites em relação a quantos dias podem ser solicitados em um único preenchimento. Para informações sobre preenchimentos, consulte Configurar um preenchimento.
Número de IDs de cliente por conta de administrador

8.000

O serviço de transferência de dados do BigQuery aceita no máximo 8.000 IDs de clientepara cada conta de administrador (MCC) do Google Ads.

Ingestão de dados de transferências do Google Ads

Ao transferir dados do Google Ads para o BigQuery, eles são carregados em tabelas do BigQuery particionadas por data. A partição da tabela em que os dados são carregados corresponde à data da fonte de dados. Se você programar várias transferências para a mesma data, o serviço de transferência de dados do BigQuery substituirá a partição dessa data específica pelos dados mais recentes. Várias transferências no mesmo dia ou preenchimentos não resultam em dados duplicados, e as partições de outras datas não são afetadas.

Limitações

  • A frequência máxima para configurar uma transferência do Google Ads é de uma vez a cada 24 horas. Por padrão, uma transferência começa no momento em que você cria a transferência. No entanto, é possível configurar o horário de início da transferência ao criar sua transferência.
  • O serviço de transferência de dados do BigQuery não é compatível com transferências incrementais durante uma transferência do Google Ads. Ao especificar uma data para uma transferência de dados, todos os dados disponíveis para essa data são transferidos.

Antes de começar

Antes de criar uma transferência do Google Ads, faça o seguinte:

Permissões exigidas

Verifique se a pessoa que está criando a transferência tem as permissões necessárias a seguir:

  • Serviço de transferência de dados do BigQuery:

    • Permissões bigquery.transfers.update para criar a transferência
    • As permissões bigquery.datasets.get e bigquery.datasets.update no conjunto de dados de destino

    O papel predefinido bigquery.admin do IAM inclui permissões bigquery.transfers.update, bigquery.datasets.update e bigquery.datasets.get. Para mais informações sobre os papéis do IAM no serviço de transferência de dados do BigQuery, consulte Referência de controle de acesso.

  • Google Ads: acesso de leitura ao ID de cliente do Google Ads ou à conta de administrador (MCC) usada na configuração de transferência.

Criar transferência de dados do Google Ads

Para criar uma transferência de dados dos relatórios do Google Ads, você precisa do ID de cliente do Google Ads ou da sua conta de administrador (MCC). Para mais informações sobre como recuperar seu ID de cliente do Google Ads, consulte Encontrar seu ID de cliente.

Para criar uma transferência de dados dos relatórios do Google Ads, selecione uma das seguintes opções:

Console

  1. Acesse a página do BigQuery no console do Google Cloud.

    Acesse a página do BigQuery

  2. Clique em Transferências de dados.

  3. Clique em Criar transferência.

  4. Na seção Tipo de origem, em Origem, escolha Google Ads.

  5. No campo Nome de exibição da seção Transferir nome da configuração, insira um nome para a transferência, como My Transfer. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.

  6. Na seção Opções de programação, faça o seguinte:

    • Em Frequência de repetição, escolha uma opção para a frequência de execução da transferência: Se você selecionar Dias, forneça um horário válido em UTC.

      • Horas
      • Dias
      • Sob demanda

    • Se aplicável, selecione Começar agora ou Começar no horário definido e forneça uma data de início e um horário de execução.

  7. Na seção Configurações de destino, em Conjunto de dados, selecione o conjunto de dados que você criou para armazenar seus dados.

  8. Na seção Detalhes da fonte de dados:

    1. Em ID de cliente, insira seu ID de cliente do Google Ads:

      Detalhes da origem do Google Ads

    2. Opcional: selecione opções para excluir itens removidos ou desativados, além de incluir tabelas novas no Google Ads.

    3. Opcional: insira uma lista de tabelas separadas por vírgulas para incluir, por exemplo, Campaign, AdGroup. Adicione o caractere - como prefixo para excluir determinadas tabelas, por exemplo, -Campaign, AdGroup. Todas as tabelas são incluídas por padrão.

    4. Opcional: selecione a opção para incluir tabelas específicas de relatórios de campanhas de maior desempenho. Para mais informações sobre a compatibilidade com PMax, consulte Suporte da PMax.

    5. Opcional: em Período de atualização, insira um valor entre 1 e 30.

  9. No menu Conta de serviço, selecione uma conta de serviço nas contas de serviço associadas ao seu projeto do Google Cloud. É possível associar uma conta de serviço à transferência em vez de usar suas credenciais de usuário. Para mais informações sobre o uso de contas de serviço com transferências de dados, consulte Usar contas de serviço.

  10. Opcional: na seção Opções de notificação

    • Clique no botão para ativar as notificações por e-mail. Quando você ativa essa opção, o administrador de transferência recebe uma notificação por e-mail se uma execução de transferência falhar.

    • Clique no botão para ativar as notificações do Pub/Sub. Em Selecionar um tópico do Cloud Pub/Sub, escolha o nome do seu tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub da sua transferência.

      Notificações do Google Ads

  11. Clique em Save.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config. As sinalizações abaixo também são obrigatórias:

  • --data_source
  • --target_dataset
  • --display_name
  • --params

As sinalizações a seguir são opcionais:

  • --project_id: especifica qual projeto usar. Se a sinalização não for especificada, o projeto padrão será usado.
  • --table_filter: especifica as tabelas a serem incluídas na transferência. Se a sinalização não for especificada, todas as tabelas serão incluídas. Para incluir apenas tabelas específicas, use uma lista de valores separados por vírgula (por exemplo, Ad, Campaign, AdGroup). Para excluir tabelas específicas, prefixe os valores com um hífen (-) (por exemplo, -Ad, Campaign, AdGroup).
  • --service_account_name: especifica uma conta de serviço a ser usada para a autenticação de transferência do Google Ads, em vez da sua conta de usuário.
bq mk \
--transfer_config \
--project_id=project_id \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source \
--table_filter=tables
--service_account_name=service_account_name

Em que:

  • project_id é o ID do projeto.
  • dataset é o conjunto de dados de destino na configuração da transferência.
  • name é o nome de exibição da configuração de transferência. O nome da transferência pode ser qualquer valor que permita identificá-la facilmente, caso precise modificá-la mais tarde.
  • parameters contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo: --params='{"param":"param_value"}'. No Google Ads, você precisa fornecer o parâmetro customer_id. Se quiser, defina o parâmetro exclude_removed_items como true para evitar a transferência de entidades e métricas removidas ou desativadas.
  • data_source é a fonte de dados: google_ads.
  • tables é a lista separada por vírgulas de tabelas a serem incluídas ou excluídas da transferência.
  • service_account_name é o nome da conta de serviço usado para autenticar a transferência. A conta de serviço precisa pertencer ao mesmo project_id usado para criar a transferência e ter todas as permissões necessárias.

Por exemplo, com o comando a seguir, você cria uma transferência do Google Ads chamada My Transfer usando o ID de cliente 123-123-1234 e o conjunto de dados de destino mydataset. A transferência é criada no projeto padrão:

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"customer_id":"123-123-1234","exclude_removed_items":"true"}' \
--data_source=google_ads

Ao executar o comando pela primeira vez, você recebe uma mensagem como esta:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Siga as instruções na mensagem e cole o código de autenticação na linha de comando.

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create ads(formerly AdWords) transfer config
public class CreateAdsTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    // the customer_id only allows digits and hyphen ('-').
    String customerId = "012-345-6789";
    String refreshWindow = "100";
    Map<String, Value> params = new HashMap<>();
    params.put("customer_id", Value.newBuilder().setStringValue(customerId).build());
    params.put("refreshWindow", Value.newBuilder().setStringValue(refreshWindow).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Ads Transfer Config Name")
            .setDataSourceId("adwords")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createAdsTransfer(projectId, transferConfig);
  }

  public static void createAdsTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Ads transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Ads transfer was not created." + ex.toString());
    }
  }
}

Acionar manualmente uma transferência do Google Ads

Quando você aciona manualmente uma transferência do Google Ads, os snapshots das tabelas de correspondência são criados uma vez por dia e armazenados na partição da data de execução mais recente. Quando você aciona uma transferência manual, os snapshots da tabela de correspondências para as tabelas a seguir não são atualizados:

  • Anúncio
  • AdGroup
  • AdGroupAudience
  • AdGroupBidModifier
  • AdGroupAdLabel
  • AdGroupCriterion
  • AdGroupCriterionLabel
  • AdGroupLabel
  • AgeRange
  • Recurso
  • AssetGroup
  • AssetGroupAsset
  • AssetGroupListingGroupFilter
  • AssetGroupSignal
  • Público-alvo
  • BidGoal
  • Budget
  • Campaign
  • CampaignAudience
  • CampaignCriterion
  • CampaignLabel
  • Cliente
  • Gender
  • Keyword
  • LocationBasedCampaignCriterion
  • ParentalStatus
  • Placement
  • Video

Suporte a campanhas de maior desempenho

Com o conector do Google Ads, é possível exportar dados de campanhas de maior desempenho. É necessário marcar a caixa de seleção Incluir tabelas da campanha Performance Max ao criar uma transferência de dados, já que os dados da PMax não são exportados por padrão.

A inclusão de dados da PMax remove os campos ad_group de determinadas tabelas e inclui novas tabelas. Não é possível incluir campos ad_group porque a API Google Ads filtra os dados PMax.

As tabelas a seguir excluem as colunas relacionadas ad_group quando a caixa de seleção Include PMax Tables está marcada:

  • GeoStats
  • GeoConversionStats
  • ShoppingProductConversionStats
  • ShoppingProductStats
  • LocationsUserLocationsStats

As tabelas a seguir são adicionadas quando a caixa de seleção Incluir tabelas de campanhas de maior desempenho é marcada:

  • Recurso
  • AssetGroup
  • AssetGroupAsset
  • AssetGroupListingGroupFilter
  • AssetGroupSignal
  • Público-alvo
  • AssetGroupProductGroupStats
  • CampaignAssetStats

Suporte para contas de administrador do Google Ads

Recomendamos aos clientes existentes que tenham várias transferências do Google Ads de ID de cliente específico que configurem uma única transferência do Google Ads no nível de conta de administrador (MCC), programem um preenchimento e desabilitem transferências do Google Ads específicas de ID de cliente individual.

O uso de contas de administrador do Google Ads oferece várias vantagens em relação ao uso de IDs de cliente individuais:

  • Não é mais necessário gerenciar várias transferências para gerar relatórios para vários IDs de cliente.
  • As consultas entre clientes são muito mais simples de escrever porque todos os IDs de cliente são armazenados na mesma tabela.
  • O uso de MCCs reduz os problemas de cota de carregamento do serviço de transferência de dados do BigQuery porque vários IDs de cliente são carregados no mesmo job.

Para mais informações sobre contas de administrador do Google Ads (MCCs), consulte Como trabalhar com contas gerenciadas e Como vincular contas à sua conta de administrador.

Exemplo

Confira na lista a seguir os IDs de cliente vinculados a determinadas contas de administrador do Google Ads:

  • 1234567890: conta de administrador raiz
    • 1234: conta de subadministrador
      • 1111: ID de cliente
      • 2222 - ID de cliente
      • 3333 - ID de cliente
      • 4444: ID de cliente
      • 567: conta de subadministrador
        • 5555: ID de cliente
        • 6666 - ID de cliente
        • 7777: ID de cliente
    • 89: conta de subadministrador
      • 8888: ID de cliente
      • 9999 - ID de cliente
    • 0000 - ID de cliente

Todo ID de cliente vinculado a uma conta de administrador é exibido em cada relatório. Para mais informações sobre a estrutura de relatórios do Google Ads no serviço de transferência de dados do BigQuery, consulte Transformação de relatórios do Google Ads.

Configuração de transferência do ID de cliente 1234567890

Uma configuração de transferência da conta de administrador raiz (ID de cliente 1234567890) geraria execuções de transferência que incluem os seguintes IDs de cliente:

  • 1111 (por meio da conta de subadministrador 1234)
  • 2222 (por meio da conta de subadministrador 1234)
  • 3333 (por meio da conta de subadministrador 1234)
  • 4444 (por meio da conta de subadministrador 1234)
  • 5555 (por meio da conta de subadministrador 567 e da conta de subadministrador 1234)
  • 6666 (por meio da conta de subadministrador 567 e da conta de subadministrador 1234)
  • 7777 (por meio da conta de subadministrador 567 e da conta de subadministrador 1234)
  • 8888 (por meio da conta de subadministrador 89)
  • 9999 (por meio da conta de subadministrador 89)
  • 0000 (ID de cliente individual)

Configuração de transferência do ID de cliente 1234

Uma configuração de transferência da conta de subadministrador 123 (ID de cliente 1234) geraria execuções de transferência que incluem os seguintes IDs de cliente:

  • 1111
  • 2222
  • 3333
  • 4444
  • 5555 (por meio da conta de subadministrador 567)
  • 6666 (por meio da conta de subadministrador 567)
  • 7777 (por meio da conta de subadministrador 567)

Configuração de transferência do ID de cliente 567

Uma configuração de transferência da conta de subadministrador 567 (ID de cliente 567) geraria execuções de transferência que incluem os seguintes IDs de cliente:

  • 5555
  • 6666
  • 7777

Configuração de transferência do ID de cliente 89

Uma configuração de transferência da conta de subadministrador 89 (ID de cliente 89) geraria execuções de transferência que incluem os seguintes IDs de cliente:

  • 8888
  • 9999

Configuração de transferência do ID de cliente 0000

Uma configuração de transferência do ID de cliente 0000 geraria execuções de transferência que incluem apenas o ID de cliente individual:

  • 0000

Migrar dados do Google Ads para MCCs

Para migrar os dados atuais do Google Ads no serviço de transferência de dados do BigQuery para a estrutura da MCC, configure um preenchimento para adicioná-los às tabelas criadas pela configuração de transferência vinculada à conta de administrador. Quando você programa um preenchimento, as tabelas de correspondência não são atualizadas.

Resolver problemas de configuração de transferência do Google Ads

Se você tiver problemas ao configurar a transferência, consulte Problemas de transferência do Google Ads em Solução de problemas das configurações de transferência.

Consultar seus dados

Quando os dados são movidos para o serviço de transferência de dados do BigQuery, eles são gravados em tabelas particionadas por tempo de processamento. Para mais informações, consulte Introdução às tabelas particionadas.

Use a pseudocoluna _PARTITIONTIME para consultar suas tabelas diretamente em vez de usar visualizações geradas automaticamente. Para mais informações, veja Como consultar tabelas particionadas.

Consultas de amostra do Google Ads

Use as consultas de amostra do Google Ads a seguir para analisar os dados transferidos. Também é possível usar as consultas em uma ferramenta de visualização, como o Looker Studio. Essas consultas são fornecidas para ajudar você a começar a consultar seus dados do Google Ads com o serviço de transferência do BigQuery. Para outras perguntas sobre o que é possível fazer com esses relatórios, entre em contato com o representante técnico do Google Ads.

Em todas as consultas a seguir, substitua dataset pelo nome do conjunto de dados. Substitua customer_id por seu ID de cliente do Google Ads.

Use a pseudocoluna _PARTITIONTIME para consultar suas tabelas diretamente em vez de usar visualizações geradas automaticamente. Para mais informações, veja Como consultar tabelas particionadas.

Desempenho da campanha

A consulta de amostra a seguir analisa o desempenho da campanha do Google Ads nos últimos 30 dias.

Console 

SELECT
  c.customer_id,
  c.campaign_name,
  c.campaign_status,
  SUM(cs.metrics_impressions) AS Impressions,
  SUM(cs.metrics_interactions) AS Interactions,
  (SUM(cs.metrics_cost_micros) / 1000000) AS Cost
FROM
  `DATASET.ads_Campaign_CUSTOMER_ID` c
LEFT JOIN
  `DATASET.ads_CampaignBasicStats_CUSTOMER_ID` cs
ON
  (c.campaign_id = cs.campaign_id
  AND cs._DATA_DATE BETWEEN
  DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY) AND DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY))
WHERE
  c._DATA_DATE = c._LATEST_DATE
GROUP BY
  1, 2, 3
ORDER BY
  Impressions DESC

bq 

  bq query --use_legacy_sql=false '
  SELECT
    c.customer_id,
    c.campaign_name,
    c.campaign_status,
    SUM(cs.metrics_impressions) AS Impressions,
    SUM(cs.metrics_interactions) AS Interactions,
    (SUM(cs.metrics_cost_micros) / 1000000) AS Cost
  FROM
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  LEFT JOIN
    `DATASET.ads_CampaignBasicStats_CUSTOMER_ID` cs
  ON
    (c.campaign_id = cs.campaign_id
    AND cs._DATA_DATE BETWEEN
    DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY) AND DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY))
  WHERE
    c._DATA_DATE = c._LATEST_DATE
  GROUP BY
    1, 2, 3
  ORDER BY
    Impressions DESC'

Contagem de palavras-chave

Na consulta de amostra a seguir, analisamos as palavras-chave por campanha, grupo de anúncios e status da palavra-chave. Nesta consulta, a função KeywordMatchType é usada. Com os tipos de correspondência de palavras-chave, você controla quais pesquisas podem acionar o anúncio. Para mais informações sobre as opções de correspondência de palavras-chave, consulte Sobre opções de correspondência de palavras-chave.

Console 

  SELECT
    c.campaign_status AS CampaignStatus,
    a.ad_group_status AS AdGroupStatus,
    k.ad_group_criterion_status AS KeywordStatus,
    k.ad_group_criterion_keyword_match_type AS KeywordMatchType,
    COUNT(*) AS count
  FROM
    `DATASET.ads_Keyword_CUSTOMER_ID` k
    JOIN
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  ON
    (k.campaign_id = c.campaign_id AND k._DATA_DATE = c._DATA_DATE)
  JOIN
    `DATASET.ads_AdGroup_CUSTOMER_ID` a
  ON
    (k.ad_group_id = a.ad_group_id AND k._DATA_DATE = a._DATA_DATE)
  WHERE
    k._DATA_DATE = k._LATEST_DATE
  GROUP BY
    1, 2, 3, 4

bq 

  bq query --use_legacy_sql=false '
  SELECT
    c.campaign_status AS CampaignStatus,
    a.ad_group_status AS AdGroupStatus,
    k.ad_group_criterion_status AS KeywordStatus,
    k.ad_group_criterion_keyword_match_type AS KeywordMatchType,
    COUNT(*) AS count
  FROM
    `DATASET.ads_Keyword_CUSTOMER_ID` k
  JOIN
    `DATASET.ads_Campaign_CUSTOMER_ID` c
  ON
    (k.campaign_id = c.campaign_id AND k._DATA_DATE = c._DATA_DATE)
  JOIN
    `DATASET.ads_AdGroup_CUSTOMER_ID` a
  ON
    (k.ad_group_id = a.ad_group_id AND k._DATA_DATE = a._DATA_DATE)
  WHERE
    k._DATA_DATE = k._LATEST_DATE
  GROUP BY
    1, 2, 3, 4'