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 être effectuées 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 grande partie de l'API Google Ads, il est important de comprendre les conventions de l'API Google Ads pour l'utiliser. Vous pouvez ignorer de nombreux aspects, tels que les jetons de développeur et l'autorisation, car les scripts Google Ads s'en chargent pour vous. Toutefois, vous devez créer une demande de mutation valide.

Voici quelques ressources de base sur l'interface REST de l'API Google Ads que vous devez connaître avant de continuer à lire 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 accepte un objet JSON qui représente un seul MutateOperation. Dans cet objet, vous spécifiez le type d'opération que vous effectuez (dans ce cas, un campaignBudgetOperation). Vous devez ensuite spécifier 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 effectuez l'opération.

Créer une opération

Il existe plusieurs stratégies que vous pouvez utiliser pour créer une opération valide. En reprenant l'exemple du budget de campagne, vous pouvez consulter la documentation de référence REST pour le budget de 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 construire un objet approprié.

Vous pouvez également essayer de créer une opération de manière dynamique à l'aide de la fonctionnalité Essayer pour le budget de la campagne. Celle-ci 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.

Reportez-vous à l'exemple ci-dessus pour voir comment fonctionne 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 requête Adsapp.search.

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 les champs dont vous souhaitez modifier 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 la 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 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 quelles erreurs se sont produites, le cas échéant.

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 permettent également d'effectuer plusieurs opérations de mutation dans une même requête à l'aide de la méthode AdsApp.mutateAll. Vous pouvez créer des entités dépendantes les unes des autres, comme une hiérarchie de campagne complète, dans une seule requête. Vous pouvez éventuellement 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'objets MutateResult, 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 celle de l'API Google Ads. Consultez 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 même requête, regroupez 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 V20, 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 : la valeur par défaut de ce champ est true. Si la valeur est définie sur true, les opérations valides sont effectuées et les opérations ayant échoué renvoient des erreurs. Si la valeur est définie sur 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éent 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});