Changement

Les scripts Google Ads sont compatibles avec les mutations génériques disponibles dans l' API Google Ads. La plupart des opérations qui peuvent être effectuées à partir de GoogleAdsService.mutate peuvent également l'être dans les scripts Google Ads, y compris la création et la gestion de campagnes.

Étant donné que cette fonctionnalité permet d'accéder à une partie aussi importante de l'API Google Ads, il est important de bien comprendre les conventions de l'API Google Ads pour l'utiliser. De nombreux aspects peuvent être ignorés, tels que les jetons de développeur et l'autorisation, car ils sont gérés par les scripts Google Ads. Toutefois, vous devez créer une requête de mutation valide.

Voici quelques ressources de base sur l'interface REST de l'API Google Ads que vous devez connaître avant de poursuivre ce guide :

Exemple de base

Pour illustrer la fonctionnalité, prenons cet exemple de base qui crée un budget de campagne :

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Un appel à AdsApp.mutate prend un objet JSON qui représente une seule MutateOperation. Dans cet objet, vous spécifiez le type d'opération que vous effectuez (dans ce cas, une campaignBudgetOperation). Vous spécifiez ensuite create, remove ou les deux update et updateMask. Les champs spécifiques dans create et update dépendent du type de ressource sur lequel vous travaillez.

Créer une opération

Vous pouvez utiliser plusieurs stratégies pour créer une opération valide. En reprenant l'exemple du budget de la campagne, vous pouvez consulter la documentation de référence REST pour le budget de la campagne afin d'afficher la liste de tous ses champs valides, puis remplir les champs appropriés ou écrire du code JavaScript personnalisé dans votre script pour créer un objet approprié.

Vous pouvez également essayer de créer une opération de manière dynamique à l'aide de la "fonctionnalité "Essayez" pour le budget de la campagne, qui vous permet de créer un corps de requête de manière dynamique en sélectionnant les champs que vous souhaitez ajouter. Vous pouvez ensuite extraire le contenu de l'opération à partir du résultat généré et l'ajouter à votre appel mutate après avoir spécifié le type d'opération.

Types d'opération

Créer

Spécifiez create dans votre opération, en transmettant une représentation d'objet de la ressource que vous souhaitez créer.

Consultez l'extrait fourni précédemment pour obtenir un exemple de l'opération create.

Supprimer

Spécifiez remove dans votre opération, en transmettant le nom de ressource de la ressource que vous souhaitez supprimer, par exemple :

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Si vous ne connaissez pas le nom de ressource d'une entité, vous pouvez le récupérer à l'aide d'une Adsapp.search requête.

Mettre à jour

Spécifiez update dans votre opération, en transmettant un objet avec le nom de ressource spécifié afin que le système puisse déterminer l'objet que vous souhaitez mettre à jour. Remplissez également tous les champs dont vous souhaitez mettre à jour les valeurs, et spécifiez un updateMask qui indique exactement les champs que vous prévoyez de modifier dans cette requête. N'incluez pas le nom de ressource dans le masque de mise à jour.

Exemple d'opération update :

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Gérer les résultats

Quel que soit le type d'opération, la valeur renvoyée est un MutateResult. Vous pouvez utiliser le nom de ressource renvoyé pour interroger l'état actuel de la ressource après la mutation et vérifier si l'opération a réussi ou si des erreurs se sont produites.

Voici un exemple illustrant un flux de base pour vérifier un résultat et imprimer des informations dans les journaux :

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Opérations multiples

Les scripts Google Ads sont également compatibles avec la mutation de plusieurs opérations dans une seule requête avec la AdsApp.mutateAll méthode. Vous pouvez créer des entités qui dépendent les unes des autres, comme une hiérarchie de campagne complète dans une seule requête. Vous pouvez également rendre l'ensemble des opérations atomique. Ainsi, si l'une d'elles échoue, aucune n'est effectuée.

La valeur renvoyée est un tableau d' MutateResult objets, un pour chaque opération que vous avez fournie et dans le même ordre que les opérations initiales.

Cette fonctionnalité fonctionne de la même manière que la fonctionnalité de l'API Google Ads. Consultez donc le guide des bonnes pratiques de l'API Google Ads pour obtenir une explication complète des ID temporaires et d'autres considérations. Notez que le guide utilise snake_case pour représenter les noms de champs, tandis que la documentation des scripts Google Ads utilise lowerCamelCase. Ces deux cas sont acceptés dans les scripts Google Ads. Vous pouvez donc copier directement le code de ce guide.

Pour effectuer plusieurs opérations dans une seule requête, collectez toutes vos opérations dans un tableau, puis appelez AdsApp.mutateAll. L'appel mutateAll prend le tableau d'opérations comme premier argument et un deuxième argument facultatif d'options, y compris :

  • apiVersion: vous pouvez spécifier une version d'API personnalisée, telle que V24, si vous souhaitez utiliser une version autre que celle par défaut des scripts. Vous pouvez utiliser n'importe quelle version disponible publiquement à ce moment-là.
  • partialFailure : ce champ est défini sur true par défaut. Si la valeur est true, les opérations valides sont effectuées et les opérations ayant échoué renvoient des erreurs. Si la valeur est false, aucune opération n'est effectuée en cas d'échec, ce qui rend cet ensemble d'opérations atomique.

Voici un exemple avec plusieurs opérations qui crée un budget de campagne, une campagne et un groupe d'annonces dans une requête atomique.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});