Transferencias de Google Ad Manager

El conector del Servicio de transferencia de datos de BigQuery para Google Ad Manager te permite crear y administrar de manera automática los datos de informe de trabajos de carga recurrentes para Google Ad Manager (antes conocido como DoubleClick for Publishers).

Informes compatibles

El conector del Servicio de transferencia de datos de BigQuery para Google Ad Manager admite las siguientes opciones de informes:

• Archivos de Transferencia de datos (Google Ad Manager DT)
• Campos de Transferencia de datos
• Tablas de coincidencias que proporciona el Servicio de transferencia de datos de BigQuery. Estos se crean y actualizan automáticamente.
• Tablas de coincidencias recuperadas con PQL
• Tablas de coincidencias de CompanyService (v201908)
• Tablas de coincidencias de OrderService (v201908)
• Tablas de coincidencias de PlacementService (v201908)

Para obtener información sobre cómo los informes de Google Ad Manager se transforman en tablas y vistas de BigQuery, consulta la página sobre transformaciones de informes de Google Ad Manager.

Nota: El Servicio de transferencia de datos de BigQuery es compatible con los siguientes delimitadores para los archivos de DT de Google Ad Manager: pestaña (\t), barra vertical (|), marca de inserción (^) y coma (,).

Opción de informe	Asistencia
Frecuencia de repetición	Cada 8 horas, según la hora de creación No configurable
Período de actualización	Últimos 2 días No configurable
Duración máxima del reabastecimiento	Últimos 60 días Google Ad Manager retiene los archivos de transferencia de datos hasta por 60 días. Google Ad Manager borra los archivos de más de 60 días.

Transferencia de datos desde transferencias de Google Ad Manager

Cuando transfieres datos de Google Ad Manager a BigQuery, estos se cargan en tablas de BigQuery particionadas por fecha. La partición de la tabla en la que se cargan los datos corresponde a la fecha de la fuente de datos. Si programas varias transferencias para la misma fecha, el Servicio de transferencia de datos de BigQuery reemplaza la partición para esa fecha específica con los datos más recientes. Las transferencias múltiples en el mismo día o los reabastecimientos en ejecución no generan datos duplicados y las particiones para otras fechas no se ven afectadas.

Períodos de actualización

El período de actualización se refiere a la cantidad de días durante los cuales una transferencia de datos recupera datos cuando se produce la transferencia. Por ejemplo, si el período de actualización es de tres días y se produce una transferencia diaria, el Servicio de transferencia de datos de BigQuery recuperará todos los datos de tu tabla de origen de los últimos tres días. En este ejemplo, cuando se produce una transferencia diaria, el Servicio de transferencia de datos de BigQuery crea una nueva partición de tabla de destino de BigQuery con una copia de los datos de la tabla de origen del día actual y, luego, activa automáticamente las ejecuciones de reabastecimiento para actualizar las particiones de la tabla de destino de BigQuery con los datos de la tabla de origen de los últimos dos días. Las ejecuciones de reabastecimiento activadas automáticamente reemplazarán o actualizarán de forma incremental tu tabla de destino de BigQuery, en base a si las actualizaciones incrementales son compatibles o no con el conector del Servicio de transferencia de datos de BigQuery.

Cuando ejecutas una transferencia de datos por primera vez, la transferencia de datos recupera todos los datos de origen disponibles dentro del período de actualización. Por ejemplo, si el período de actualización es de tres días y ejecutas la transferencia de datos por primera vez, el Servicio de transferencia de datos de BigQuery recupera todos los datos de origen en un plazo de tres días.

Las ventanas de actualización se asignan al campo de API TransferConfig.data_refresh_window_days.

Para recuperar datos fuera del período de actualización, como datos históricos, o para recuperar datos de interrupciones o brechas de transferencia, puedes iniciar o programar una ejecución de reabastecimiento.

Actualizaciones incrementales

Las tablas que se crean a partir de los archivos de transferencia de datos de Google Ad Manager (Google Ad Manager DT) se pueden actualizar de forma incremental. Google Ad Manager agrega los archivos de Google Ad Manager DT al bucket de Cloud Storage. Luego, una ejecución de transferencia carga de forma incremental los nuevos archivos DT de Google Ad Manager del bucket de Cloud Storage en la tabla de BigQuery sin volver a cargar los archivos que ya se transfirieron a la tabla de BigQuery.

Por ejemplo, Google Ad Manager agrega file1 al bucket a la 1:00 a.m. y file2 a las 2:00 a.m. Una ejecución de transferencia comienza a las 3:30 a.m. y carga file1 y file2 en BigQuery. Luego, Google Ad Manager agrega file3 a las 5:00 a.m. y file4 a las 6:00 a.m. Una segunda ejecución de transferencia comienza a las 7:30 a.m. y agrega file3 y file4 a BigQuery, en lugar de reemplazar la tabla cargando los cuatro archivos.

Antes de comenzar

Antes de crear una transferencia de datos de Google Ad Manager, haz lo siguiente:

• Verifica si completaste todas las acciones necesarias para habilitar el servicio de transferencia de datos de BigQuery.
• Crea un conjunto de datos de BigQuery para almacenar los datos de Google Ad Manager.

• Asegúrate de que tu organización tenga acceso a los archivos de Transferencia de datos de Google Ad Manager (Google Ad Manager DT). Estos archivos los entrega el equipo de Google AD Manager a un bucket de Google Cloud Storage. Para obtener acceso a los archivos de Google Ad Manager DT, consulta los informes de Transferencia de datos de Ad Manager. Se pueden aplicar cargos adicionales del equipo de Google Ad Manager.

  Después de completar este paso, recibirás un bucket de Cloud Storage similar al siguiente:

      gdfp-12345678
    

  El equipo de Google Cloud NO tiene la capacidad de generar los archivos de Google Ad Manager DT o conceder acceso a ellos en tu nombre. Comunícate con la asistencia de Google Ad Manager para acceder a los archivos de Google Ad Manager DT.

• Habilita el acceso a la API para tu red de Google Ad Manager.
• Si deseas configurar las notificaciones de transferencia de datos, debes tener permisos pubsub.topics.setIamPolicy para Pub/Sub. Los permisos de Pub/Sub no son necesarios si solo configuras las notificaciones por correo electrónico. Para obtener más información, consulta las notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.

Permisos necesarios

• BigQuery: Asegúrate de que la persona que crea la transferencia de datos tenga los siguientes permisos en BigQuery:

  • Los permisos bigquery.transfers.update para crear la transferencia de datos
  • Los permisos bigquery.datasets.get y bigquery.datasets.update en el conjunto de datos de destino

  La función predefinida de IAM bigquery.admin incluye los permisos bigquery.transfers.update, bigquery.datasets.update y bigquery.datasets.get. Para obtener más información sobre los roles de IAM en el Servicio de transferencia de datos de BigQuery, consulta Control de acceso.

• Google Ad Manager: Acceso de lectura a los archivos de Google Ad Manager DT almacenados en Cloud Storage. Los permisos para los archivos de Google Ad Manager DT los administra el equipo de Google Ad Manager. Además de los archivos de Google Ad Manager DT, la persona que crea la transferencia de datos debe agregarse a la red de Google Ad Manager, con acceso de lectura a todas las entidades necesarias para crear las diversastablas de coincidencias (elemento de una sola línea, pedido, bloque de anuncios, etcétera). Para ello, agrega el usuario de Ad Manager que autenticó la transferencia de datos al equipo Todas las entidades en Ad Manager.

Configura una transferencia de Google Ad Manager

Para configurar una transferencia de datos para Google Ad Manager se requiere lo siguiente:

• Depósito de Cloud Storage: El URI del depósito de Cloud Storage para tus archivos de Google Ad Manager DT como se describe en Antes de comenzar El nombre del bucket debe parecerse a este:

  gdfp-12345678

• Código de red: Encontrarás el código de red de Google Ad Manager en la URL cuando accedas a tu red. Por ejemplo, en la URL https://admanager.google.com/2032576#delivery, 2032576 es tu código de red. Para obtener más información, consulta la página sobre cómo comenzar a usar Google Ad Manager.

Para crear una transferencia de datos con el Servicio de transferencia de datos de BigQuery para Google Ad Manager:

Console

1. Ve a la página Transferencia de datos en la consola de Google Cloud.

   Ir a Transferencias de datos

2. Haz clic en Crear una transferencia.

3. En la página Crear transferencia, sigue estos pasos:

   • En la sección Tipo de fuente (Source type), en Fuente (Source), elige Google Ad Manager (antes DFP).

   

   • En la sección Nombre de la configuración de transferencia (Transfer config name), en Nombre visible, ingresa el nombre de la transferencia de datos, como My Transfer. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.

   

   • En la sección Configuración de destino, en Conjunto de datos, elige el conjunto de datos que creaste para almacenar tus datos.

   

   • En la sección Detalles de la fuente de datos, haz lo siguiente:
     • En Bucket de Cloud Storage (Cloud Storage bucket), ingresa el nombre del bucket de Cloud Storage que contiene tus archivos de transferencia de datos. Cuando ingreses el nombre del bucket, no incluyas gs://.
     • En Código de red (Network code), ingresa el código de tu red.

   

   • En el menú Cuenta de servicio, selecciona una cuenta de servicio de las cuentas de servicio asociadas a tu proyecto de Google Cloud. Puedes asociar una cuenta de servicio con tu transferencia en lugar de usar tus credenciales de usuario. Para obtener más información sobre el uso de cuentas de servicio con transferencias de datos, consulta Usa cuentas de servicio.
     
     Si accediste con una identidad federada, se requiere una cuenta de servicio para crear una transferencia. Si accediste con una Cuenta de Google, la cuenta de servicio para la transferencia es opcional. La cuenta de servicio debe tener los permisos necesarios.

   • De forma opcional, en la sección Opciones de notificación, haz lo siguiente:

     • Haz clic en el botón de activación para habilitar las notificaciones por correo electrónico. Cuando habilitas esta opción, el administrador de transferencias recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
     • Haz clic en el botón de activación para habilitar las notificaciones de ejecución de Pub/Sub. Para Seleccionar un tema de Cloud Pub/Sub, elige el nombre de tu tema o haz clic en Crear un tema. Esta opción configura las notificaciones de ejecución de Pub/Sub para tu transferencia.

4. Haz clic en Guardar.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config. También se requieren las siguientes marcas:

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

Marcas opcionales:

• --service_account_name: Especifica una cuenta de servicio que se usará para autenticar la transferencia de Google Ad Manager en lugar de tu cuenta de usuario.

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

Donde:

• project_id es el ID del proyecto.
• dataset es el conjunto de datos de destino para la configuración de la transferencia.
• name es el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia de datos puede ser cualquier valor que te permita identificarla si es necesario hacerle modificaciones más tarde.
• parameters contiene los parámetros para la configuración de la transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}' Para Google Ad Manager, debes proporcionar los parámetros bucket y network_code. bucket es el depósito de Cloud Storage que contiene los archivos de Google Ad Manager DT. network_code es el código de red.
• data_source es la fuente de datos, dfp_dt (Google Ad Manager).
• service_account_name es el nombre de la cuenta de servicio que se usa para autenticar tu transferencia de datos. La cuenta de servicio debe ser propiedad del mismo project_id que se usa para crear la transferencia y debe tener todos los permisos necesarios.

Precaución: No se puede configurar notificaciones mediante la herramienta de línea de comandos.

También puedes proporcionar la marca --project_id para especificar un proyecto en particular. Si no se especifica --project_id, se usa el proyecto predeterminado.

Por ejemplo, el siguiente comando crea una transferencia de datos de Google Ad Manager llamada My Transfer mediante el código de red 12345678, el bucket gdfp-12345678 de Cloud Storage y el conjunto de datos de destino mydataset. La transferencia de datos se crea en el proyecto predeterminado:

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

Después de ejecutar el comando, recibirás un mensaje como el siguiente:

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

Sigue las instrucciones y pega el código de autenticación en la línea de comandos.

API

Usa el método projects.locations.transferConfigs.create y suministra una instancia del recurso TransferConfig.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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());
    }
  }
}

Advertencia: Si cambias el esquema de un informe, todos los archivos de ese día deben tener el mismo esquema o la transferencia de datos de todo el día fallará.

Soluciona problemas de configuración de transferencia de Google Ad Manager

Si tienes problemas con la configuración de tu transferencia de datos, consulta la sección sobre cómo solucionar problemas de transferencia de Google Ad Manager en la página acerca de cómo solucionar problemas de configuración de la transferencia.

Consulta tus datos

Cuando tus datos se transfieren a BigQuery, se escriben en tablas particionadas por tiempo de transferencia. Para obtener más información, consulta Introducción a tablas con particiones.

Si consultas tus tablas directamente en lugar de usar las vistas generadas de manera automática, debes usar la seudocolumna _PARTITIONTIME en tu consulta. Para obtener más información, visita la página Consulta tablas particionadas.

Consultas de muestra de Google Ad Manager

Puedes usar las siguientes consultas de muestra de Google Ad Manager para analizar los datos transferidos. También puedes usar las consultas en una herramienta de visualización, como Looker Studio. Estas consultas se proporcionan para ayudarte a comenzar a consultar tus datos de Google Ad Manager con BigQuery. Si tienes preguntas adicionales sobre lo que puedes hacer con estos informes, comunícate con tu representante técnico de Google Ad Manager.

Nota: Si consultas las tablas directamente en lugar de usar las vistas generadas de manera automática, debes usar la seudocolumna _PARTITIONTIME en tu consulta. Para obtener más información, visita Consulta tablas particionadas.

En cada una de las siguientes consultas, reemplaza variables como dataset por tus valores. Por ejemplo, reemplaza network_code por tu código de red de Google Ad Manager.

Impresiones y usuarios únicos por ciudad

La siguiente consulta de muestra en SQL analiza el número de impresiones y usuarios únicos por ciudad en los últimos 30 días.

# 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

Impresiones y usuarios únicos por tipo de elemento de una sola línea

La siguiente consulta de muestra en SQL analiza el número de impresiones y usuarios únicos por tipo de elemento de una sola línea en los últimos 30 días.

# 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

Impresiones por bloque de anuncios

La siguiente consulta de muestra en SQL analiza el número de impresiones por bloque de anuncios en los últimos 30 días.

# 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

Impresiones por elemento de una sola línea

La siguiente consulta de muestra en SQL analiza el número de impresiones por elemento de una sola línea en los últimos 30 días.

# 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