Modification

Les scripts Google Ads sont compatibles avec les mutations génériques disponibles dans l'API Google Ads. La plupart des opérations pouvant ê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.

Comme cette fonctionnalité permet d'accéder à une grande partie de l'API Google Ads, il est important de comprendre les bases des 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 pour vous par les scripts Google Ads. Toutefois, vous devez créer une requête de modification 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 cette fonctionnalité, prenons l'exemple de base suivant, qui crée un budget de campagne :

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

Un appel à AdsApp.mutate utilise 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, campaignBudgetOperation). Vous devez ensuite spécifier create, remove, ou à la fois update et updateMask. Les champs spécifiques de 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 sur le budget de la campagne pour 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é "Essayer" 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.

Pour obtenir un exemple de l'opération create, consultez l'extrait fourni précédemment.

Supprimer

Spécifiez remove dans votre opération, en transmettant le nom 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. Renseignez également les champs dont vous souhaitez mettre à jour les valeurs, puis spécifiez un paramètre 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 un MutateResult. Vous pouvez utiliser le nom de ressource renvoyé pour interroger l'état actuel de la ressource après la modification, et vérifier si l'opération a réussi ou quelles erreurs se sont produites, le cas échéant.

Voici un exemple de flux de base permettant de vérifier un résultat et d'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 de modifier plusieurs opérations 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, de sorte que 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 le code directement à partir de ce guide.

Pour effectuer plusieurs opérations dans une seule requête, rassemblez toutes vos opérations dans un tableau, puis appelez AdsApp.mutateAll. L'appel mutateAll utilise 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 V26, 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, l'échec d'une opération entraîne l'annulation de toutes les opérations, 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});