Les scripts Google Ads sont compatibles avec les mutates 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 des 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 connaître les principes de base des conventions de l'API Google Ads afin de l'utiliser. De nombreux aspects peuvent être ignorés, tels que les jetons de développeur et les autorisations, car ils sont gérés pour vous par les scripts Google Ads, mais vous devez former une demande mutate valide.
Voici quelques ressources de base sur l'interface REST de l'API Google Ads que vous devez connaître avant de poursuivre la lecture de 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, un campaignBudgetOperation). Spécifiez ensuite create, remove ou les deux.updateupdateMask Les champs spécifiques dans create et update dépendent du type de ressource spécifique sur lequel vous effectuez des opérations.
Créer une opération
Plusieurs stratégies permettent de créer une opération valide. Reprenons l'exemple du budget de campagne. Dans la documentation de référence REST sur le budget d'une campagne, vous pouvez consulter la liste de tous les champs valides, puis remplir les champs appropriés. Vous pouvez aussi écrire un code JavaScript personnalisé dans votre script afin de créer un objet approprié.
Vous pouvez également essayer de créer une opération dynamiquement à l'aide de la fonctionnalité Essayer cette fonctionnalité 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 indiquant 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 la ressource d'une entité, vous pouvez l'extraire à 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 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 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"
}
});
Traiter 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 le mutate et vérifier si l'opération a réussi ou identifier les erreurs qui se sont produites, le cas échéant.
Voici un exemple illustrant un processus de base pour vérifier un résultat et imprimer certaines 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 rendre des entités dépendantes les unes des autres, par exemple une hiérarchie de campagne complète dans une seule requête. Vous pouvez éventuellement rendre l'ensemble complet des opérations atomique. Ainsi, si l'une d'entre 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 la fonctionnalité de l'API Google Ads. Par conséquent, consultez le guide des bonnes pratiques de l'API Google Ads pour obtenir une explication complète des ID temporaires et d'autres éléments à prendre en compte. Notez que le guide utilise snake_case pour représenter les noms de champs, alors que la documentation sur les 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 des options, y compris:
apiVersion: vous pouvez spécifier une version d'API personnalisée, telle queV16, si vous souhaitez utiliser une version autre que la version par défaut des scripts. Vous pouvez alors utiliser n'importe quelle version accessible au public.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 ayant échoué renvoient des erreurs. Si la valeur estfalse, en cas d'échec d'une opération, aucune opération n'est effectuée, 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});