Transferts Google Ad Manager

Le connecteur du service de transfert de données BigQuery pour Google Ad Manager vous permet de créer et de gérer automatiquement des tâches de chargement récurrentes pour les données de rapports Google Ad Manager (anciennement DoubleClick for Publishers).

Rapports acceptés

Le connecteur du service de transfert de données BigQuery pour Google Ad Manager accepte les options de création de rapports suivantes:

• Fichiers de transfert de données (Google Ad Manager DT)
• Champs de transfert de données
• Tables des correspondance fournies par le service de transfert de données BigQuery Elles sont automatiquement créées et mises à jour.
• Tables de correspondance extraites avec PQL
• Tables de correspondance de CompanyService (v201908)
• Tables de correspondance de OrderService (v201908)
• Tables de correspondance de PlacementService (v201908)

Pour plus d'informations sur la transformation des rapports Google Ad Manager en tables et vues BigQuery, consultez la page Transformation des rapports Google Ad Manager.

Remarque : Le service de transfert de données BigQuery est compatible avec les délimiteurs suivants pour les fichiers Google Ad Manager DT : tabulation (\t), barre verticale (|), caret (^) et virgule (,).

Option de création de rapports	Compatibilité
Fréquence de répétition	Toutes les 8 heures, en fonction de l'heure de création. Non configurable
Intervalle d'actualisation	Les deux derniers jours Non configurable
Durée maximale du remplissage	Les 60 derniers jours Google Ad Manager conserve les fichiers de transfert de données pendant 60 jours maximum. Les fichiers de plus de 60 jours sont supprimés par Google Ad Manager.

Ingestion de données à partir de transferts Google Ad Manager

Lorsque vous transférez des données de Google Ad Manager vers BigQuery, elles sont chargées dans des tables BigQuery partitionnées par date. La partition de la table dans laquelle les données sont chargées correspond à la date de la source de données. Si vous planifiez plusieurs transferts pour la même date, le service de transfert de données BigQuery remplace la partition de cette date spécifique par les données les plus récentes. Plusieurs transferts le même jour ou l'exécution de remplissages n'entraînent pas de données en double, et les partitions des autres dates ne sont pas affectées.

Actualiser les fenêtres

Un intervalle d'actualisation correspond au nombre de jours pendant lesquels un transfert de données récupère des données lors d'un transfert de données. Par exemple, si la fenêtre d'actualisation est de trois jours et qu'un transfert quotidien a lieu, le service de transfert de données BigQuery récupère toutes les données de votre table source des trois derniers jours. Dans cet exemple, lorsqu'un transfert quotidien a lieu, le service de transfert de données BigQuery crée une partition de table de destination BigQuery avec une copie des données de votre table source du jour, puis déclenche automatiquement des exécutions de remplissage pour mettre à jour les partitions de table de destination BigQuery avec les données de votre table source des deux jours précédents. Les opérations de remplissage déclenchées automatiquement écrasent ou mettent à jour de manière incrémentielle votre table de destination BigQuery, selon que les mises à jour incrémentielles sont ou non compatibles avec le connecteur du service de transfert de données BigQuery.

Lorsque vous exécutez un transfert de données pour la première fois, celui-ci récupère toutes les données sources disponibles pendant l'intervalle d'actualisation. Par exemple, si la fenêtre d'actualisation est de trois jours et que vous exécutez le transfert de données pour la première fois, le service de transfert de données BigQuery récupère toutes les données sources dans un délai de trois jours.

Les fenêtres d'actualisation sont mappées sur le champ d'API TransferConfig.data_refresh_window_days.

Pour récupérer des données en dehors de la période d'actualisation, telles que des données historiques, ou pour récupérer des données en cas d'indisponibilité ou d'écarts de transfert, vous pouvez lancer ou planifier une exécution de remplissage.

Mises à jour incrémentielles

Les tables créées à partir de fichiers de transfert de données Google Ad Manager (Google Ad Manager DT) peuvent être mises à jour de manière incrémentielle. Google Ad Manager ajoute les fichiers Google Ad Manager DT au bucket Cloud Storage. Une exécution de transfert charge ensuite de manière incrémentielle les nouveaux fichiers DT Google Ad Manager à partir du bucket Cloud Storage dans la table BigQuery, sans recharger les fichiers déjà transférés vers la table BigQuery.

Par exemple, Google Ad Manager ajoute file1 dans le bucket à 1h00 et file2 à 2h00. Une exécution de transfert commence à 3h30 et charge file1 et file2 dans BigQuery. Google Ad Manager ajoute ensuite file3 à 5h00 et file4 à 6h00. Une deuxième exécution de transfert commence à 7h30 et ajoute file3 et file4 dans BigQuery, au lieu d'écraser la table en chargeant les quatre fichiers.

Avant de commencer

Avant de créer un transfert de données Google Ad Manager:

• Vérifiez que vous avez effectué toutes les actions requises pour activer le service de transfert de données BigQuery.
• Créez un ensemble de données BigQuery pour stocker les données Google Ad Manager.

• Assurez-vous que votre organisation a accès aux fichiers de transfert de données Google Ad Manager (Google Ad Manager DT). Ces fichiers sont transmis par l'équipe Google Ad Manager à un bucket Cloud Storage. Pour accéder aux fichiers DT de Google Ad Manager, consultez les rapports sur le transfert de données Ad Manager. Des frais supplémentaires peuvent vous être facturés par l'équipe Google Ad Manager.

  Une fois cette étape terminée, vous recevez un bucket Cloud Storage semblable à celui-ci :

      gdfp-12345678
    

  L'équipe Google Cloud ne peut PAS générer ni attribuer de droits d'accès aux fichiers Google Ad Manager en votre nom. Contactez l'assistance Google Ad Manager pour accéder aux fichiers Google Ad Manager DT.

• Activez l'accès à l'API pour votre réseau Google Ad Manager.
• Si vous avez l'intention de configurer des notifications de transfert de données pour Pub/Sub, vous devez disposer des autorisations pubsub.topics.setIamPolicy. Les autorisations Pub/Sub ne sont pas nécessaires si vous ne configurez que des notifications par e-mail. Pour en savoir plus, consultez la page Notifications d'exécution du service de transfert de données BigQuery.

Autorisations requises

• BigQuery : assurez-vous que la personne qui crée le transfert de données dispose des autorisations suivantes dans BigQuery :

  • Autorisations bigquery.transfers.update pour créer le transfert de données
  • Autorisations bigquery.datasets.get et bigquery.datasets.update sur l'ensemble de données cible

  Le rôle IAM prédéfini bigquery.admin inclut les autorisations bigquery.transfers.update, bigquery.datasets.update et bigquery.datasets.get. Pour en savoir plus sur les rôles IAM associés au service de transfert de données BigQuery, consultez la page Contrôle des accès.

• Google Ad Manager : accès en lecture aux fichiers Google Ad Manager DT stockés dans Cloud Storage. Les autorisations pour les fichiers Google Ad Manager DT sont gérées par l'équipe Google Ad Manager. Outre les fichiers Google Ad Manager DT, la personne qui crée le transfert de données doit être ajoutée au réseau Google Ad Manager, avec un accès en lecture à toutes les entités nécessaires à la création des différentes tables de correspondance (élément de campagne, campagne, bloc d'annonces, etc.). Pour y parvenir, ajoutez l'utilisateur Ad Manager qui a authentifié le transfert de données à l'équipe "Toutes les entités" dans Ad Manager.

Configurer un transfert Google Ad Manager

Pour configurer un transfert de données BigQuery pour Google Ad Manager, vous devez disposer des éléments suivants :

• Bucket Cloud Storage : l'URI du bucket Cloud Storage pour vos fichiers Google Ad Manager DT, comme décrit dans la section Avant de commencer. Le nom du bucket doit ressembler à ceci :

  gdfp-12345678

• Code réseau : le code réseau Google Ad Manager est visible dans l'URL lorsque vous êtes connecté à votre réseau. Par exemple, dans l'URL https://admanager.google.com/2032576#delivery, 2032576 correspond à votre code réseau. Pour en savoir plus, consultez la page Premiers pas avec Google Ad Manager.

Pour créer un transfert de données BigQuery pour Google Ad Manager:

Console

1. Accédez à la page "Transferts de données" dans la console Google Cloud.

   Accéder à la page Transferts de données

2. Cliquez sur Créer un transfert.

3. Sur la page Créer un transfert :

   • Dans la section Source type (Type de source), choisissez Google Ad Manager (formerly DFP) (Google Ad Manager (anciennement DFP)) comme Source.

   

   • Dans la section Transfer config name (Nom de la configuration de transfert), sous Display name (Nom à afficher), saisissez un nom pour le transfert de données, tel que My Transfer. Ce nom peut correspondre à toute valeur permettant d'identifier le transfert si vous devez le modifier ultérieurement.

   

   • Dans la section Paramètres de destination, pour le champ Ensemble de données, choisissez l'ensemble de données que vous avez créé pour stocker vos données.

   

   • Dans la section Data source details (Détails de la source de données) :
     • Pour Bucket Cloud Storage, saisissez le nom du bucket Cloud Storage qui stocke vos fichiers de transfert de données. N'incluez pas gs:// dans votre saisie.
     • Pour Code réseau, saisissez votre code réseau.

   

   • Dans le menu Compte de service, sélectionnez un compte de service parmi ceux associés à votre projet Google Cloud. Vous pouvez associer un compte de service à votre transfert au lieu d'utiliser vos identifiants utilisateur. Pour en savoir plus sur l'utilisation des comptes de service avec des transferts de données, consultez la page Utiliser des comptes de service.
     
     Si vous vous êtes connecté avec une identité fédérée, vous devez disposer d'un compte de service pour créer un transfert. Si vous vous êtes connecté avec un compte Google, un compte de service pour le transfert est facultatif. Le compte de service doit disposer des autorisations requises.

   • (Facultatif) Dans la section Notification options (Options de notification) :

     • Cliquez sur le bouton pour activer les notifications par e-mail. Lorsque vous activez cette option, l'administrateur de transfert reçoit une notification par e-mail en cas d'échec de l'exécution du transfert.
     • Cliquez sur le bouton pour activer les notifications d'exécution Pub/Sub. Dans le champ Sélectionner un sujet Cloud Pub/Sub, choisissez le nom de votre sujet ou cliquez sur Créer un sujet. Cette option configure les notifications d'exécution Pub/Sub pour votre transfert.

4. Cliquez sur Enregistrer.

bq

Saisissez la commande bq mk, puis spécifiez l'indicateur de création de transfert --transfer_config. Les paramètres suivants sont également requis :

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

Indicateurs facultatifs :

• --service_account_name : indique un compte de service à utiliser pour l'authentification du transfert Google Ad Manager au lieu de votre compte utilisateur.

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

Où :

• project_id est l'ID de votre projet.
• dataset est l'ensemble de données cible de la configuration de transfert.
• name est le nom à afficher pour la configuration du transfert de données. Ce nom peut correspondre à toute valeur permettant d'identifier le transfert de données si vous devez le modifier ultérieurement.
• parameters contient les paramètres de la configuration de transfert créée au format JSON. Exemple : --params='{"param":"param_value"}'. Pour Google Ad Manager, vous devez indiquer les paramètres bucket et network_code. bucket correspond au bucket Cloud Storage contenant vos fichiers Google Ad Manager DT. network_code est votre code réseau.
• data_source représente la source de données : dfp_dt (Google Ad Manager).
• service_account_name est le nom du compte de service utilisé pour authentifier le transfert de données. Le compte de service doit appartenir au même project_id que celui utilisé pour créer le transfert et doit disposer de toutes les autorisations requises.

Attention : Actuellement, vous ne pouvez pas configurer de notifications à l'aide de l'outil de ligne de commande.

Vous pouvez également indiquer l'option --project_id pour spécifier un projet particulier. Si --project_id n'est pas spécifié, le projet par défaut est utilisé.

Par exemple, la commande suivante crée un transfert de données Google Ad Manager nommé My Transfer utilisant le code réseau 12345678, le bucket Cloud Storage gdfp-12345678 et l'ensemble de données cible mydataset. Le transfert de données est créé dans le projet par défaut:

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

Après avoir exécuté la commande, vous recevez un message de ce type :

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

Suivez les instructions et collez le code d'authentification sur la ligne de commande.

API

Utilisez la méthode projects.locations.transferConfigs.create et fournissez une instance de la ressource TransferConfig.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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());
    }
  }
}

Attention : Si vous modifiez le schéma d'un rapport, tous les fichiers du jour concerné doivent avoir le même schéma. Si ce n'est pas le cas, le transfert échoue pour la journée entière.

Résoudre les problèmes de configuration des transferts Google Ad Manager

Si vous rencontrez des problèmes lors de la configuration de votre transfert de données, consultez la section Problèmes de transfert avec Google Ad Manager de la page Dépannage des configurations de transferts.

Interroger les données

Lorsque les données sont transférées vers BigQuery, elles sont écrites dans des tables partitionnées avec date d'ingestion. Pour plus d'informations, consultez la page Présentation des tables partitionnées.

Si vous interrogez directement les tables au lieu d'utiliser les vues générées automatiquement, vous devez utiliser la pseudo-colonne _PARTITIONTIME dans votre requête. Pour en savoir plus, consultez la page Interroger des tables partitionnées.

Exemples de requêtes Google Ad Manager

Vous pouvez utiliser les exemples de requêtes Google Ad Manager suivants pour analyser les données transférées. Vous pouvez également interroger les données dans un outil de visualisation tel que Looker Studio. Ces requêtes sont fournies pour vous guider dans l'interrogation des données Google Ad Manager avec BigQuery. Pour en savoir plus sur ce que vous pouvez faire avec ces rapports, contactez votre représentant technique Google Ad Manager.

Remarque : Si vous interrogez directement vos tables au lieu d'utiliser les vues générées automatiquement, vous devez utiliser la pseudo-colonne _PARTITIONTIME dans votre requête. Pour en savoir plus, consultez la page Interroger des tables partitionnées.

Dans chacune des requêtes suivantes, remplacez les variables comme dataset par vos valeurs. Par exemple, remplacez network_code par votre code réseau Google Ad Manager.

Impressions et utilisateurs uniques par ville

L'exemple de requête SQL suivant analyse le nombre d'impressions et d'utilisateurs uniques par ville au cours des 30 derniers jours.

# 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

Impressions et utilisateurs uniques par type d'élément de campagne

L'exemple de requête SQL suivant analyse le nombre d'impressions et d'utilisateurs uniques par type d'élément de campagne au cours des 30 derniers jours.

# 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

Impressions par bloc d'annonces

L'exemple de requête SQL suivant analyse le nombre d'impressions par bloc d'annonces au cours des 30 derniers jours.

# 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

Impressions par élément de campagne

L'exemple de requête SQL suivant analyse le nombre d'impressions par élément de campagne au cours des 30 derniers jours.

# 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