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 ê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 base de l'API Google Ads pour pouvoir l'utiliser. Vous pouvez ignorer de nombreux aspects, tels que les jetons de développeur et l'autorisation, car ils sont gérés par les scripts Google Ads. Vous devez toutefois 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é, considérez 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 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 de create et update dépendent du type de ressource spécifique sur lequel vous travaillez.
Créer une opération
Il existe plusieurs stratégies que vous pouvez utiliser pour créer une opération valide. Pour rester sur l'exemple du budget de la campagne, vous pouvez consulter la documentation de référence REST sur le budget de la campagne pour obtenir 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 fonction "Essayez ceci" 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.
Vous trouverez ci-dessus un exemple d'opération create.
Supprimer
Spécifiez remove dans votre opération, en transmettant le nom de la 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 la ressource spécifié afin que le système puisse déterminer l'objet que vous souhaitez mettre à jour. De plus, remplissez tous les champs pour lesquels 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 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 la 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 de modifier plusieurs opérations dans une seule 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 campagnes 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 concernant 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 champ, 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 même requête, collectez toutes vos opérations dans un tableau, puis appelez AdsApp.mutateAll. L'appel mutateAll utilise le tableau d'opérations comme premier argument et comme deuxième argument facultatif d'options, y compris:
apiVersion: vous pouvez spécifier une version d'API personnalisée, telle queV18, si vous souhaitez utiliser une version autre que celle par défaut des scripts. Vous pouvez utiliser n'importe quelle version publique disponible à ce moment-là.partialFailure: la valeur par défaut de ce champ esttrue. Si la valeur esttrue, les opérations valides sont effectuées et les opérations échouées renvoient des erreurs. Si la valeur est définie surfalse, aucune opération n'est effectuée en cas d'échec d'une opération, ce qui rend cet ensemble d'opérations atomique.
Voici un exemple d'opérations multiples 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});