Bonnes pratiques

Cette page présente différentes bonnes pratiques pour développer des scripts Google Ads.

Sélecteurs

Filtrer avec des sélecteurs

Dans la mesure du possible, utilisez des filtres pour ne demander que les entités dont vous avez besoin. L'application de filtres appropriés présente les avantages suivants :

• Le code est plus simple et plus facile à comprendre.
• Le script s'exécutera bien plus rapidement.

Comparez les extraits de code suivants :

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 10')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  // Do work here.
}

var keywords = AdsApp.keywords().get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor(
      'LAST_MONTH');
  if (stats.getClicks() > 10) {
    // Do work here.
  }
}

La deuxième approche n'est pas recommandée, car elle tente de récupérer la liste de tous les mots clés de votre compte uniquement pour appliquer un filtre à la liste.

Éviter de parcourir la hiérarchie de la campagne

Lorsque vous souhaitez récupérer des entités à un niveau particulier, utilisez une méthode de collecte à ce niveau au lieu de parcourir toute la hiérarchie de la campagne. En plus d'être plus simple, cette méthode sera également beaucoup plus performante : le système n'aura pas à lire inutilement toutes les campagnes et tous les groupes d'annonces.

Comparez les extraits de code suivants qui récupèrent toutes les annonces de votre compte :

var ads = AdsApp.ads();

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next().
      adGroups().get();
  while (adGroups.hasNext()) {
    var ads = adGroups.next().ads().get();
    // Do your work here.
  }
}

La deuxième approche n'est pas recommandée, car elle tente de récupérer des hiérarchies entières d'objets (campagnes, groupes d'annonces), alors que seules les annonces sont nécessaires.

Utiliser des méthodes d'accesseur parent spécifiques

Vous devez parfois obtenir l'entité parente d'un objet récupéré. Dans ce cas, vous devez utiliser une méthode d'accesseur fournie au lieu de récupérer des hiérarchies entières.

Comparez les extraits de code suivants qui récupèrent les groupes d'annonces contenant des annonces textuelles ayant généré plus de 50 clics le mois dernier :

var ads = AdsApp.ads()
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup) to an array.
}

var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    if (ads.totalNumEntities() > 0) {
      // Store (campaign, adGroup) to an array.
    }
  }
}

La deuxième approche n'est pas recommandée, car elle récupère l'ensemble des hiérarchies de campagnes et de groupes d'annonces de votre compte, alors que vous n'avez besoin que d'un sous-ensemble de campagnes et de groupes d'annonces associés à votre ensemble d'annonces. La première approche se limite à récupérer uniquement la collection d'annonces pertinente et utilise une méthode appropriée pour accéder à ses objets parents.

Utiliser des filtres parents spécifiques

Pour accéder à des entités dans une campagne ou un groupe d'annonces spécifiques, utilisez un filtre spécifique dans le sélecteur au lieu d'extraire les données, puis de parcourir une hiérarchie.

Comparez les extraits de code suivants qui récupèrent la liste des annonces textuelles dans une campagne et un groupe d'annonces spécifiques ayant généré plus de 50 clics le mois dernier.

var ads = AdsApp.ads()
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup, ad) to
  // an array.
}

var campaigns = AdsApp.campaigns()
    .withCondition('Name = "Campaign 1"')
    .get();

while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .withCondition('Name = "AdGroup 1"')
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    while (ads.hasNext()) {
      var ad = ads.next();
      // Store (campaign, adGroup, ad) to
      // an array.
    }
  }
}

La deuxième approche n'est pas recommandée, car elle itère sur la hiérarchie des campagnes et des groupes d'annonces de votre compte, alors que vous n'avez besoin que d'un ensemble sélectionné d'annonces, ainsi que de leurs campagnes et groupes d'annonces parents. La première approche limite l'itération à la liste des annonces en appliquant un filtre spécifique pour les entités parentes sur le sélecteur.

Utiliser des ID pour le filtrage, si possible

Lorsque vous filtrez des entités, il est préférable de les filtrer par leur ID plutôt que par d'autres champs.

Prenons l'exemple des extraits de code suivants qui sélectionnent une campagne.

var campaign = AdsApp.campaigns()
    .withIds([12345])
    .get()
    .next();

var campaign = AdsApp.campaigns()
    .withCondition('Name="foo"')
    .get()
    .next();

La deuxième approche est moins optimale, car nous filtrons par un champ non lié à un ID.

Filtrer par ID parentaux dans la mesure du possible

Lorsque vous sélectionnez une entité, filtrez par ID parent dans la mesure du possible. Cela accélérera vos requêtes en limitant la liste des entités récupérées par les serveurs lors du filtrage des résultats.

Prenons l'extrait de code suivant qui récupère un groupe d'annonces par son ID. Supposons que l'ID de la campagne parente soit connu.

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .withCondition('CampaignId="54678"')
    .get()
    .next();

var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .get()
    .next();

Bien que les deux extraits de code donnent des résultats identiques, le filtrage supplémentaire dans l'extrait de code 1 à l'aide d'un ID parent (CampaignId="54678") rend le code plus efficace en limitant la liste des entités que le serveur doit parcourir lors du filtrage des résultats.

Utiliser des libellés lorsque le nombre de conditions de filtrage est trop élevé

Lorsque vous avez trop de conditions de filtrage, il est judicieux de créer un libellé pour les entités que vous traitez et de l'utiliser pour filtrer vos entités.

Prenons l'exemple de l'extrait de code suivant, qui récupère une liste de campagnes par leur nom.

var label = AdsApp.labels()
    .withCondition('Name = "My Label"')
    .get()
    .next();
var campaigns = label.campaigns.get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work
}

var campaignNames = [‘foo’, ‘bar’, ‘baz’];

for (var i = 0; i < campaignNames.length; i++) {
  campaignNames[i] = '"' + campaignNames[i] + '"';
}

var campaigns = AdsApp.campaigns
    .withCondition('CampaignName in [' + campaignNames.join(',') + ']')
    .get();

while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work.
}

Bien que les deux extraits de code offrent un niveau de performances similaire, la deuxième approche tend à générer un code plus complexe à mesure que le nombre de conditions dans votre sélecteur augmente. Il est également plus facile d'appliquer le libellé à une nouvelle entité que de modifier le script pour inclure une nouvelle entité.

Limitez le nombre de conditions dans votre clause IN.

Lorsque vous exécutez des scripts, un cas d'utilisation courant consiste à générer un rapport pour une liste d'entités. Les développeurs y parviennent généralement en créant une très longue requête AWQL qui filtre les ID d'entité à l'aide d'une clause IN. Cette approche fonctionne bien lorsque le nombre d'entités est limité. Toutefois, à mesure que la longueur de votre requête augmente, les performances de votre script se détériorent pour deux raisons :

• Plus une requête est longue, plus elle prend de temps à analyser.
• Chaque ID que vous ajoutez à une clause IN est une condition supplémentaire à évaluer, ce qui prend donc plus de temps.

Dans ce cas, il est préférable d'appliquer un libellé aux entités, puis de filtrer par LabelId.

// The label applied to the entity is "Report Entities"
var label = AdsApp.labels()
    .withCondition('LabelName contains "Report Entities"')
    .get()
    .next();

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT ' +
    'WHERE LabelId = "' + label.getId() + '"');

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT WHERE ' +
    'AdGroupId IN (123, 456) and Id in (123,345, 456…)');

Modifications du compte

Regrouper les modifications

Lorsque vous modifiez une entité Google Ads, les scripts Google Ads n'exécutent pas immédiatement la modification. Au lieu de cela, il tente de combiner plusieurs modifications en lots afin de pouvoir émettre une seule requête qui effectue plusieurs modifications. Cette approche accélère vos scripts et réduit la charge sur les serveurs Google Ads. Toutefois, certains modèles de code forcent les scripts Google Ads à vider fréquemment leur lot d'opérations, ce qui ralentit l'exécution de votre script.

Prenons l'exemple du script suivant, qui met à jour les enchères d'une liste de mots clés.

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

var list = [];
while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  list.push(keyword);
}

for (var i = 0; i < list.length; i++) {
  var keyword = list[i];
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

La deuxième approche n'est pas recommandée, car l'appel à keyword.bidding().getCpc() force les scripts Google Ads à vider l'opération setCpc() et à n'exécuter qu'une seule opération à la fois. La première approche, bien que similaire à la seconde, présente l'avantage supplémentaire de prendre en charge le traitement par lot, car l'appel getCpc() est effectué dans une boucle distincte de celle où setCpc() est appelé.

Utiliser des compilateurs si possible

Les scripts Google Ads permettent de créer des objets de deux manières : à l'aide de builders et de méthodes de création. Les builders sont plus flexibles que les méthodes de création, car ils vous donnent accès à l'objet créé à partir de l'appel d'API.

Prenons les extraits de code suivants :

var operation = adGroup.newKeywordBuilder()
    .withText('shoes')
    .build();
var keyword = operation.getResult();

adGroup.createKeyword('shoes');
var keyword = adGroup.keywords()
    .withCondition('KeywordText="shoes"')
    .get()
    .next();

La deuxième approche n'est pas recommandée en raison de l'opération de sélection supplémentaire nécessaire pour récupérer le mot clé. De plus, les méthodes de création sont également obsolètes.

Toutefois, gardez à l'esprit que les builders, lorsqu'ils sont utilisés de manière incorrecte, peuvent empêcher les scripts Google Ads de regrouper leurs opérations.

Considérez les extraits de code suivants qui créent une liste de mots clés et affichent l'ID des mots clés nouvellement créés :

var keywords = [‘foo’, ‘bar’, ‘baz’];

var list = [];
for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  list.push(operation);
}

for (var i = 0; i < list.length; i++) {
  var operation = list[i];
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

var keywords = [‘foo’, ‘bar’, ‘baz’];

for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

La deuxième approche n'est pas recommandée, car elle appelle operation.getResult() dans la même boucle qui crée l'opération, ce qui oblige les scripts Google Ads à exécuter une opération à la fois. La première approche, bien que similaire, permet le traitement par lot, car nous appelons operation.getResult() dans une boucle différente de celle où il a été créé.

Envisagez d'utiliser les importations groupées pour les mises à jour importantes.

Les développeurs exécutent souvent des rapports et mettent à jour les propriétés des entités (par exemple, les enchères de mots clés) en fonction des valeurs de performances actuelles. Lorsque vous devez mettre à jour un grand nombre d'entités, les importations groupées ont tendance à offrir de meilleures performances. Par exemple, prenons les scripts suivants qui augmentent le CPC max des mots clés dont le TopImpressionPercentage > 0.4 pour le mois dernier :

var report = AdsApp.report(
  'SELECT AdGroupId, Id, CpcBid FROM KEYWORDS_PERFORMANCE_REPORT ' +
  'WHERE TopImpressionPercentage > 0.4 DURING LAST_MONTH');

var upload = AdsApp.bulkUploads().newCsvUpload([
  report.getColumnHeader('AdGroupId').getBulkUploadColumnName(),
  report.getColumnHeader('Id').getBulkUploadColumnName(),
  report.getColumnHeader('CpcBid').getBulkUploadColumnName()]);
upload.forCampaignManagement();

var reportRows = report.rows();
while (reportRows.hasNext()) {
  var row = reportRows.next();
  row['CpcBid'] = row['CpcBid'] + 0.02;
  upload.append(row.formatForUpload());
}

upload.apply();

var reportRows = AdsApp.report('SELECT AdGroupId, Id, CpcBid FROM ' +
    'KEYWORDS_PERFORMANCE_REPORT WHERE TopImpressionPercentage > 0.4 ' +
    ' DURING LAST_MONTH')
    .rows();

var map = {
};

while (reportRows.hasNext()) {
  var row = reportRows.next();
  var adGroupId = row['AdGroupId'];
  var id = row['Id'];

  if (map[adGroupId] == null) {
    map[adGroupId] = [];
  }
  map[adGroupId].push([adGroupId, id]);
}

for (var key in map) {
  var keywords = AdsApp.keywords()
      .withCondition('AdGroupId="' + key + '"')
      .withIds(map[key])
      .get();

  while (keywords.hasNext()) {
    var keyword = keywords.next();
    keyword.bidding().setCpc(keyword.bidding().getCpc() + 0.02);
  }
}

Bien que la deuxième approche offre de bonnes performances, la première est préférable dans ce cas, car

• Les scripts Google Ads sont soumis à une limite concernant le nombre d'objets pouvant être récupérés ou mis à jour en une seule exécution. Les opérations de sélection et de mise à jour de la deuxième approche sont comptabilisées dans cette limite.

• Les importations groupées ont des limites plus élevées en termes de nombre d'entités qu'elles peuvent mettre à jour et de durée d'exécution globale.

Regroupez vos importations groupées par campagne

Lorsque vous créez vos importations groupées, essayez de regrouper vos opérations par campagne parente. Cela permet d'améliorer l'efficacité et de réduire le risque de conflits de modifications ou d'erreurs de concurrence.

Prenons l'exemple de deux tâches d'importation groupée exécutées en parallèle. L'un met en veille les annonces d'un groupe d'annonces, tandis que l'autre ajuste les enchères de mots clés. Même si les opérations ne sont pas liées, elles peuvent s'appliquer à des entités du même groupe d'annonces (ou à deux groupes d'annonces différents de la même campagne). Dans ce cas, le système verrouille l'entité parente (le groupe d'annonces ou la campagne partagés), ce qui entraîne le blocage mutuel des tâches d'importation groupée.

Les scripts Google Ads peuvent optimiser l'exécution d'une seule tâche d'importation groupée. La solution la plus simple consiste donc à n'exécuter qu'une seule tâche d'importation groupée par compte à la fois. Si vous décidez d'effectuer plusieurs importations groupées par compte, assurez-vous qu'elles fonctionnent sur des listes de campagnes (et de leurs entités enfants) mutuellement exclusives pour des performances optimales.

Rapports

Utiliser les rapports pour récupérer des statistiques

Lorsque vous souhaitez récupérer de grandes quantités d'entités et leurs statistiques, il est souvent préférable d'utiliser des rapports plutôt que les méthodes AdsApp standards. Nous vous recommandons d'utiliser des rapports pour les raisons suivantes :

• Les rapports vous permettent d'obtenir de meilleures performances pour les requêtes volumineuses.
• Les rapports n'atteindront pas les quotas de récupération normaux.

Comparez les extraits de code suivants qui récupèrent les clics, les impressions, le coût et le texte de tous les mots clés ayant généré plus de 50 clics le mois dernier :

  report = AdsApp.search(
      'SELECT ' +
      '   ad_group_criterion.keyword.text, ' +
      '   metrics.clicks, ' +
      '   metrics.cost_micros, ' +
      '   metrics.impressions ' +
      'FROM ' +
      '   keyword_view ' +
      'WHERE ' +
      '   segments.date DURING LAST_MONTH ' +
      '   AND metrics.clicks > 50');
  while (report.hasNext()) {
    var row = report.next();
    Logger.log('Keyword: %s Impressions: %s ' +
        'Clicks: %s Cost: %s',
        row.adGroupCriterion.keyword.text,
        row.metrics.impressions,
        row.metrics.clicks,
        row.metrics.cost);
  }

var keywords = AdsApp.keywords()
    .withCondition('metrics.clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor('LAST_MONTH');
  Logger.log('Keyword: %s Impressions: %s ' +
      'Clicks: %s Cost: %s',
      keyword.getText(),
      stats.getImpressions(),
      stats.getClicks(),
      stats.getCost());
}

La deuxième approche n'est pas recommandée, car elle itère sur les mots clés et récupère les statistiques une entité à la fois. Les rapports sont plus rapides dans ce cas, car ils récupèrent toutes les données en un seul appel et les diffusent en streaming selon les besoins. De plus, les mots clés récupérés dans la deuxième approche sont comptabilisés dans le quota de votre script pour le nombre d'entités récupérées à l'aide d'un appel get().

Utiliser la recherche au lieu d'un rapport

La méthode de rapport a été conçue pour l'ancienne infrastructure et génère des résultats dans un format plat, même si vous utilisez GAQL. Cela signifie qu'il doit transformer les résultats de la requête pour qu'ils correspondent à l'ancien style, ce qui n'est pas compatible avec tous les champs et ajoute une surcharge à chaque appel.

Nous vous suggérons d'utiliser la recherche pour profiter de toutes les fonctionnalités des nouveaux rapports de l'API Google Ads.

Préférer GAQL à AWQL

Bien qu'AWQL soit toujours compatible avec les requêtes de rapport et les appels withCondition, il est exécuté via une couche de traduction qui n'est pas entièrement compatible avec le véritable AWQL. Pour contrôler entièrement vos requêtes, assurez-vous d'utiliser GAQL.

Si vous avez des requêtes AWQL existantes que vous souhaitez traduire, nous avons un outil de migration des requêtes pour vous aider.

Ne sélectionnez pas plus de lignes que nécessaire.

La vitesse d'exécution des rapports (et des sélecteurs) dépend du nombre total de lignes que le rapport renverrait, que vous les parcouriez ou non. Cela signifie que vous devez toujours utiliser des filtres spécifiques pour minimiser autant que possible l'ensemble de résultats afin qu'il corresponde à votre cas d'utilisation.

Par exemple, imaginons que vous souhaitiez trouver des groupes d'annonces dont les enchères se situent en dehors d'une plage spécifique. Il serait plus rapide d'effectuer deux requêtes distinctes (une pour les enchères inférieures au seuil bas et une autre pour les enchères supérieures au seuil haut) que de récupérer tous les groupes d'annonces et d'ignorer ceux qui ne vous intéressent pas.

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros < 1000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros > 2000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}

var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group');

while (report.hasNext()) {
  var row = report.next();
  var cpcBidMicros = row.adGroup.cpcBidMicros;
  if (cpcBidMicros < 1000000 || cpcBidMicros > 2000000) {
    adGroups.push(row.adGroup);
  }
}

Scripts Ads Manager (CM)

Privilégier executeInParallel à l'exécution séquentielle

Lorsque vous écrivez des scripts pour des comptes administrateur, utilisez executeInParallel() au lieu de l'exécution séquentielle, si possible. executeInParallel() donne à votre script plus de temps de traitement (jusqu'à une heure) et jusqu'à 30 minutes par compte traité (au lieu de 30 minutes combinées pour l'exécution en série). Pour en savoir plus, consultez notre page sur les limites.

Feuilles de calcul

Utiliser des opérations par lots pour mettre à jour des feuilles de calcul

Lorsque vous mettez à jour des feuilles de calcul, essayez d'utiliser les méthodes d'opération groupée (par exemple, getRange()) plutôt que les méthodes qui mettent à jour une cellule à la fois.

Prenons l'exemple de l'extrait de code suivant qui génère un motif fractal dans une feuille de calcul.

var colors = new Array(100);
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  colors[y] = new Array(100);
  for (var x = 0; x < 100; x++) {
    colors[y][x] = getColor_(xcoord, ycoord);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
}
sheet.getRange(1, 1, 100, 100).setBackgroundColors(colors);

var cell = sheet.getRange('a1');
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  for (var x = 0; x < 100; x++) {
    var c = getColor_(xcoord, ycoord);
    cell.offset(y, x).setBackgroundColor(c);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
  SpreadsheetApp.flush();
}

Bien que Google Sheets tente d'optimiser le deuxième extrait de code en mettant en cache les valeurs, il offre toujours de mauvaises performances par rapport au premier extrait, en raison du nombre d'appels d'API effectués.