Transferências do Google Ad Manager

Com o serviço de transferência de dados do BigQuery para o conector do Google Ad Manager, é possível criar e gerenciar automaticamente jobs de carregamento recorrentes de dados de relatório do Google Ad Manager (antigo DoubleClick for Publishers).

Relatórios compatíveis

O conector do serviço de transferência de dados do BigQuery para Google Ad Manager é compatível com as seguintes opções de relatórios:

• Arquivos de transferência de dados (DT do Google Ad Manager)
• Campos de transferência de dados
• Tabelas de correspondência fornecidas pelo serviço de transferência de dados do BigQuery. Elas são criadas e atualizadas automaticamente.
• Tabelas de correspondência buscadas com PQL
• Tabelas de correspondência do CompanyService (v201908)
• Tabelas de correspondência do OrderService (v201908)
• Tabelas de correspondência do PlacementService (v201908)

Para informações sobre como os relatórios do Google Ad Manager são transformados em tabelas e visualizações do BigQuery, consulte este artigo.

Observação: o serviço de transferência de dados do BigQuery aceita os seguintes delimitadores de arquivos DT do Google Ad Manager: tabulação ( \t ), barra vertical ( | ), acento circunflexo ( ^ ) e vírgula ( , ).

Opção de relatório	Suporte
Repetir frequência	A cada 8 horas, com base no tempo de criação. Não configurável
Atualizar janela	Últimos 2 dias Não configurável
Duração máxima do preenchimento	Últimos 60 dias O Google Ad Manager mantém os arquivos da transferência de dados por até 60 dias. Arquivos com mais de 60 dias são excluídos pelo Google Ad Manager.

Ingestão de dados de transferências do Google Ad Manager

Ao transferir dados do Google Ad Manager 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.

Atualizar janelas

Uma janela de atualização é o número de dias que uma transferência de dados recupera dados quando ocorre uma transferência de dados. Por exemplo, se a janela de atualização for de três dias e uma transferência diária ocorrer, o serviço de transferência de dados do BigQuery vai extrair todos os dados da tabela de origem dos últimos três dias. Nesse exemplo, quando uma transferência diária ocorre, o serviço de transferência de dados do BigQuery cria uma nova partição de tabela de destino do BigQuery com uma cópia dos dados da tabela de origem do dia atual e, em seguida, aciona automaticamente as execuções de preenchimento para atualizar as partições de tabela de destino do BigQuery com os dados da tabela de origem dos últimos dois dias. As execuções de preenchimento automático acionadas automaticamente vão substituir ou atualizar de forma incremental a tabela de destino do BigQuery, dependendo de se as atualizações incrementais são aceitas ou não pelo conector do serviço de transferência de dados do BigQuery.

Quando você executa uma transferência de dados pela primeira vez, ela recupera todos os dados de origem disponíveis na janela de atualização. Por exemplo, se a janela de atualização for de três dias e você executar a transferência de dados pela primeira vez, o serviço de transferência de dados do BigQuery vai recuperar todos os dados de origem em três dias.

As janelas de atualização são mapeadas para o campo da APITransferConfig.data_refresh_window_days.

Para recuperar dados fora da janela de atualização, como dados históricos, ou para recuperar dados de interrupções ou lacunas de transferência, inicie ou programe uma execução de preenchimento.

Atualizações incrementais

As tabelas criadas a partir de arquivos de transferência de dados do Google Ad Manager (DT do Google Ad Manager) podem ser atualizadas de forma incremental. O Google Ad Manager adiciona os arquivos DT do Google Ad Manager ao bucket do Cloud Storage. Uma execução de transferência carrega de forma incremental os novos arquivos DT do Google Ad Manager do bucket do Cloud Storage na tabela do BigQuery sem recarregar os arquivos que já foram transferidos.

Por exemplo: o Google Ad Manager adiciona file1 ao bucket às 1h e file2 às 2h. Uma transferência começa às 3h30 e carrega file1 e file2 para o BigQuery. O Google Ad Manager adiciona file3 às 5h e file4 às 6h. Uma segunda execução de transferência começa às 7h30 e anexa file3 e file4 ao BigQuery, em vez de substituir a tabela ao carregar os quatro arquivos.

Antes de começar

Antes de criar uma transferência de dados do Google Ad Manager, siga estas recomendações:

• Verifique se você realizou todas as ações necessárias para ativar o serviço de transferência de dados do BigQuery.
• Crie um conjunto de dados do BigQuery para armazenar os dados do Google Ad Manager.

• Certifique-se de que sua organização tenha acesso aos arquivos de transferência de dados do Google Ad Manager (DT do Google Ad Manager). Esses arquivos são entregues pela equipe do Google Ad Manager a um bucket do Cloud Storage. Para ter acesso aos arquivos DT do Google Ad Manager, consulte os relatórios da Transferência de dados do Ad Manager. Sujeito a cobranças adicionais da equipe do Google Ad Manager.

  Após concluir esta etapa, você receberá um bucket do Cloud Storage semelhante a este:

      gdfp-12345678
    

  A equipe do Google Cloud NÃO pode gerar ou conceder acesso a arquivos DT do Google Ad Manager em seu nome. Entre em contato com o suporte do Google Ad Manager para ter acesso aos arquivos DT.

• Ative o acesso da API à sua rede do Google Ad Manager.
• Se você pretende configurar notificações de transferência de dados, é necessário ter as permissões pubsub.topics.setIamPolicy do Pub/Sub. As permissões do Pub/Sub não serão necessárias caso você configure notificações por e-mail. Para mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.

Permissões necessárias

• BigQuery: verifique se a pessoa que está criando a transferência de dados tem as permissões a seguir no BigQuery:

  • Permissões bigquery.transfers.update para criar a transferência de dados
  • 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 o controle de acesso.

• Google Ad Manager: acesso de leitura aos arquivos DT do Google Ad Manager armazenados no Cloud Storage. As permissões para arquivos DT do Google Ad Manager são gerenciadas pela equipe do Google Ad Manager. Além dos arquivos DT do Google Ad Manager, a pessoa que cria a transferência de dados precisa ser adicionada à rede do Google Ad Manager, com acesso de leitura a todas as entidades necessárias para criar as várias tabelas de correspondências (item de linha, pedido, bloco de anúncios etc.). Para isso, é preciso adicionar o usuário do Ad Manager que autenticou a transferência de dados para a equipe "Todas as entidades" no Ad Manager.

Configurar uma transferência do Google Ad Manager

Requisitos para configurar uma transferência de dados do BigQuery para o Google Ad Manager:

• Bucket do Cloud Storage: o URI do bucket do Cloud Storage referente aos arquivos DT do Google Ad Manager, conforme descrito em Antes de começar. O nome do bucket é semelhante a este:

  gdfp-12345678

• Código de rede: você verá o código de rede do Google Ad Manager no URL quando estiver conectado à rede. Por exemplo, no URL https://admanager.google.com/2032576#delivery, 2032576 é o código de rede. Para mais informações, consulte Primeiros passos com o Google Ad Manager.

Para criar uma transferência de dados do serviço de transferência de dados do BigQuery, faça o seguinte:

Console

1. Acesse a página "Transferências de dados" no console do Google Cloud.

   Acesse Transferências de dados

2. Clique em Criar uma transferência.

3. Na página Criar transferência:

   • Na seção Tipo de origem, em Origem, escolha Google Ad Manager (antigo DFP).

   

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

   

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

   

   • Na seção Detalhes da fonte de dados:
     • Em bucket do Cloud Storage, insira o nome do bucket do Cloud Storage que armazena os arquivos de transferência de dados. Ao inserir esse nome, não inclua gs://.
     • Em Código de rede, insira o código da rede.

   

   • 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.
     
     Se você fez login com uma identidade federada, é necessário uma conta de serviço para criar uma transferência. Se você fez login com uma Conta do Google, uma conta de serviço para a transferência é opcional. A conta de serviço precisa ter as permissões necessárias.

   • 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 de execução do Pub/Sub. Em Selecionar um tópico do Cloud Pub/Sub, escolha o nome do tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub para sua transferência.

4. Clique em Salvar.

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

Sinalizações opcionais:

• --service_account_name: especifica uma conta de serviço para usar na autenticação de transferência do Google Ad Manager em vez de 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 \
--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 de dados. O nome da transferência de dados 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 Ad Manager, você precisa fornecer os parâmetros bucket e network_code. bucket é o bucket do Cloud Storage que contém seus arquivos DT do Google Ad Manager. network_code é seu código de rede;
• data_source é a fonte de dados: dfp_dt (Google Ad Manager).
• service_account_name é o nome da conta de serviço usado para autenticar a transferência de dados. 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.

Atenção: no momento, não é possível configurar notificações usando a ferramenta de linha de comando.

Também é possível fornecer a sinalização --project_id para especificar um projeto determinado. Se --project_id não for especificado, o projeto padrão será usado.

Por exemplo, o comando a seguir cria uma transferência de dados do Google Ad Manager chamada My Transfer usando o código de rede 12345678, o bucket do Cloud Storage gdfp-12345678 e o conjunto de dados de destino mydataset. A transferência de dados é criada no projeto padrão:

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"bucket": "gdfp-12345678","network_code": "12345678"}' \
--data_source=dfp_dt

Após executar o comando, você recebe uma mensagem semelhante a 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 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 a ad manager(formerly DFP) transfer config
public class CreateAdManagerTransfer {

  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";
    String bucket = "gs://cloud-sample-data";
    // the network_code can only be digits with length 1 to 15
    String networkCode = "12345678";
    Map<String, Value> params = new HashMap<>();
    params.put("bucket", Value.newBuilder().setStringValue(bucket).build());
    params.put("network_code", Value.newBuilder().setStringValue(networkCode).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Ad Manager Config Name")
            .setDataSourceId("dfp_dt")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createAdManagerTransfer(projectId, transferConfig);
  }

  public static void createAdManagerTransfer(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("Ad manager transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Ad manager transfer was not created." + ex.toString());
    }
  }
}

Alerta: se você alterar o esquema de um relatório, todos os arquivos nesse dia precisarão ter o mesmo esquema. Caso contrário, a transferência de dados do dia inteiro falhará.

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

Se você tiver problemas para configurar a transferência de dados, consulte Problemas de transferência do Google Ad Manager em Solução de problemas de configurações de transferência.

Consultar dados

Quando os dados são transferidos para o 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 Ad Manager

Use as consultas de amostra do Google Ad Manager a seguir para analisar seus 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 você começar a consultar seus dados do Google Ad Manager com o BigQuery. Se tiver mais dúvidas sobre o que é possível fazer com esses relatórios, entre em contato com seu representante técnico do Google Ad Manager.

Observação: use a pseudocoluna _PARTITIONTIME para consultar suas tabelas diretamente em vez de utilizar visualizações geradas automaticamente. Para mais informações, veja Como consultar tabelas particionadas.

Em todas as consultas a seguir, substitua variáveis como dataset por seus valores. Por exemplo, substitua network_code pelo código de rede do Google Ad Manager.

Impressões e usuários únicos por cidade

Na seguinte consulta de amostra SQL, o número de impressões e usuários únicos é analisado por cidade nos últimos 30 dias.

# START_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY)
# END_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY)
SELECT
  City,
  _DATA_DATE AS Date,
  count(*) AS imps,
  count(distinct UserId) AS uniq_users
FROM `dataset.NetworkImpressionsnetwork_code`
WHERE
  _DATA_DATE BETWEEN start_date AND end_date
GROUP BY City, Date

Impressões e usuários únicos por tipo de item de linha

Na seguinte consulta de amostra do SQL, o número de impressões e usuários únicos é analisado por tipo de item de linha nos últimos 30 dias.

# START_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY)
# END_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY)
SELECT
  MT.LineItemType AS LineItemType,
  DT._DATA_DATE AS Date,
  count(*) AS imps,
  count(distinct UserId) AS uniq_users
FROM `dataset.NetworkImpressionsnetwork_code` AS DT
LEFT JOIN `dataset.MatchTableLineItem_network_code` AS MT
ON
  DT.LineItemId = MT.Id
WHERE
  DT._DATA_DATE BETWEEN start_date AND end_date
GROUP BY LineItemType, Date
ORDER BY Date desc, imps desc

Impressões por bloco de anúncios

Na seguinte consulta de amostra SQL, o número de impressões é analisado por bloco de anúncios nos últimos 30 dias.

# START_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY)
# END_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY)
SELECT
  MT.AdUnitCode AS AdUnitCode,
  DT.DATA_DATE AS Date,
  count(*) AS imps
FROM `dataset.NetworkImpressionsnetwork_code` AS DT
LEFT JOIN `dataset.MatchTableLineItem_network_code` AS MT
ON
  DT.AdUnitId = MT.Id
WHERE
  DT._DATA_DATE BETWEEN start_date AND end_date
GROUP BY AdUnitCode, Date
ORDER BY Date desc, imps desc

Impressões por item de linha

Na seguinte consulta de amostra SQL, o número de impressões é analisado por item de linha nos últimos 30 dias.

# START_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -31 DAY)
# END_DATE = DATE_ADD(CURRENT_DATE(), INTERVAL -1 DAY)
SELECT
  MT.Name AS LineItemName,
  DT._DATA_DATE AS Date,
  count(*) AS imps
FROM `dataset.NetworkImpressionsnetwork_code` AS DT
LEFT JOIN `dataset.MatchTableLineItem_network_code` AS MT
ON
  DT.LineItemId = MT.Id
WHERE
  DT._DATA_DATE BETWEEN start_date AND end_date
GROUP BY LineItemName, Date
ORDER BY Date desc, imps desc