Accès à un seul compte
Si vous souhaitez accéder à un seul compte d’utilisateur, tout commence par l’objet AdsApp .
Comment faire accéder aux entités de mon compte ?
Utilisez AdsApp pour accéder à toutes les entités du compte. L’objet contient une méthode de sélecteur pour chaque type d’entité (par exemple, les campagnes, les groupes d’annonces et les mots clés). La méthode de sélecteur retourne toutes les entités pour ce type d’entité. Par exemple, pour obtenir tous les groupes d’annonces dans le compte, appelez la adGroups() méthode .
var iterator = AdsApp.adGroups().get();
Mais que se passe-t-il si je veux une entité spécifique ou un sous-ensemble d’entités ?
Le sélecteur fournit différentes façons de filtrer la liste des entités. Vous pouvez utiliser la méthode du withIds() sélecteur pour obtenir des entités spécifiques par ID ou vous pouvez utiliser withCondition() pour spécifier les critères de sélection pour sélectionner les entités. Les sélecteurs pour tous les types d’entités, à l’exception des listes de mot clé négatives, permettent de filtrer la liste des entités.
Utilisez la notation par points pour chaîner plusieurs filtres ensemble. Si vous spécifiez plusieurs filtres, ils sont traités comme une opération AND : le sélecteur retourne uniquement les entités qui correspondent à toutes les conditions.
Pour obtenir tous les groupes d’annonces d’une campagne, utilisez la withCondition() méthode pour spécifier le nom de la campagne.
var campaignName = 'My Campaign';
var iterator = AdsApp.adGroups()
.withCondition(`CampaignName = '${campaignName}'`)
.get();
Pour obtenir la liste des conditions et des opérateurs que vous pouvez utiliser pour filtrer la liste des entités, consultez la méthode du withCondition() sélecteur. Par exemple, pour obtenir la liste des conditions de groupe d’annonces, consultez la méthode withCondition du sélecteur de groupe d’annonces.
Pour obtenir un groupe d’annonces par ID, utilisez la withIds() méthode pour spécifier le groupe d’annonces à obtenir.
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
Vous pouvez également obtenir le groupe d’annonces par nom.
var campaignName = 'My Campaign';
var adGroupName = 'My AdGroup';
var iterator = AdsApp.adGroups()
.withCondition(`CampaignName = '${campaignName}'`)
.withCondition(`Name = '${adGroupName}'`)
.get();
Pour plus d’informations sur les sélecteurs, consultez Que sont les sélecteurs ?
Comment faire utiliser le sélecteur pour itérer dans la liste filtrée des entités ?
Vous ne le faites pas. Le sélecteur définit simplement les entités que vous souhaitez obtenir. Pour obtenir réellement les entités, vous utilisez un itérateur. Pour obtenir l’itérateur, vous appelez la méthode du get() sélecteur.
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
Utilisez une boucle while simple pour itérer sur la liste des entités.
while (iterator.hasNext()) {
var adGroup = iterator.next();
// Do something with the entity
}
Pour plus d’informations sur les itérateurs, consultez Que sont les itérateurs ?
Comment faire obtenir des données de performances pour une entité ?
La plupart des entités vous permettent de demander des données de performances, le cas échéant. Mais vous devez d’abord indiquer à Scripts la plage de dates pour les données de performances lorsque vous spécifiez le sélecteur. Pour spécifier une plage de dates, utilisez un littéral prédéfini, tel que HIER ou LAST_MONTH, ou utilisez une date de début et de fin. Pour plus d’informations, consultez forDateRange(string dateRange) et forDateRange(Object dateFrom, Object dateTo).
var campaignName = 'My Campaign';
var adGroupName = 'My AdGroup';
var iterator = AdsApp.adGroups()
.forDateRange('LAST_30_DAYS')
.withCondition(`CampaignName = '${campaignName}'`)
.withCondition(`Name = '${adGroupName}'`)
.get();
while (iterator.hasNext()) {
var adGroup = iterator.next();
var stats = adGroup.getStats();
}
Vous devez également spécifier une plage de dates si vous spécifiez une colonne de données de performances dans la méthode d’un withCondition() sélecteur. Par exemple, si vous souhaitez uniquement des groupes d’annonces dont le taux de récupération est supérieur à 0,22 %, vous devez spécifier une plage de dates.
var startDate = {year: 2018, month: 6, day: 3};
var endDate = {year: 2018, month: 6, day: 13};
var iterator = AdsApp.adGroups()
.forDateRange(startDate, endDate)
.withCondition("Ctr > 0.22")
.get();
Comment faire ajouter une entité ?
Pour ajouter une entité, vous utilisez un objet de générateur. Pour obtenir un objet générateur, appelez la méthode new* sur l’objet parent auquel vous ajoutez des enfants. Par exemple, pour ajouter des groupes d’annonces à une campagne, appelez la méthode de la newAdGroupBuilder() campagne.
L’objet générateur contient des méthodes permettant de définir toutes les propriétés de l’objet que vous êtes autorisé à spécifier. Il inclut également une build() méthode que vous utilisez pour créer l’entité. L’exemple suivant montre comment créer un groupe d’annonces. (Pour plus d’informations sur l’obtention d’un objet de campagne, consultez Obtenir une campagne par nom.)
var adGroupName = "My ad group";
var endDate = {year: 2018, month: 6, day: 13};
var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};
var adGroupOperation = campaign.newAdGroupBuilder()
.withName(adGroupName)
.withStatus('ENABLED')
.withLanguage('English')
.withBiddingStrategy('MANUAL_CPC')
.withCpc(1.2)
.withCustomParameters(customParameters)
.withEndDate(endDate)
.build();
La build méthode retourne un objet d’opération, que vous pouvez utiliser pour case activée si Scripts a correctement créé l’entité. L’exemple suivant illustre le modèle d’appel classique. Appelez la getResult méthode uniquement si vous souhaitez accéder aux propriétés de la nouvelle entité.
if (adGroupOperation.isSuccessful()) {
var adGroup = adGroupOperation.getResult();
}
else {
for (var error of adGroupOperation.getErrors()) {
Logger.log(`${error}\n`);
}
}
Pour plus d’informations sur les générateurs et les considérations relatives aux performances lors de l’appel des méthodes d’opération, consultez Que sont les générateurs ?
Comment faire mettre à jour une entité ?
Après avoir utilisé un objet générateur pour ajouter une entité, vous utilisez les méthodes de l’entité pour mettre à jour ses propriétés. L’exemple suivant met à jour le montant de l’enchère AUT du groupe d’annonces.
var ids = ["123456789"];
var adGroups = AdsApp.adGroups()
.withIds(ids)
.get();
if (adGroups.hasNext()) {
var adGroup = adGroups.next();
adGroup.bidding().setCpc(2.5);
}
Mais comment savoir que la mise à jour a fonctionné ?
Si vous essayez de mettre à jour une propriété avec une valeur non valide, Scripts écrit une erreur dans le journal des modifications, mais il ne lève pas d’exception, de sorte que votre script continue à s’exécuter. N’obtenez pas la propriété après la mise à jour vers case activée si la propriété contient la nouvelle valeur ; cela a un impact négatif sur les performances.
function main() {
var id = "123456789";
var bidAmount = -2.5;
var keyword = getKeyword(id);
if (keyword != null) {
keyword.bidding().setCpc(bidAmount); // Bid is not set because bid amount is not valid
}
}
function getKeyword(id) {
var keywords = AdsApp.keywords()
.withIds([id])
.get();
if (keywords.hasNext()) {
return keywords.next();
}
else {
return null;
}
}
Écriture dans le fichier journal
Scripts fournit un fichier journal dans lequel écrire des informations de suivi et de débogage. Pour plus d’informations, consultez Journaux des modifications et journaux de texte.