Exemples de script pour la gestion des étiquettes

Les sections suivantes présentent des exemples de scripts qui effectuent différentes actions sur des étiquettes.

Ajouter des étiquettes à un compte

Pour utiliser des étiquettes, commencez par les ajouter à votre compte. Vous pouvez ajouter un maximum de 100 000 étiquettes à un compte. Pour ajouter une étiquette, utilisez la méthode createLabel . La méthode prend comme entrée le nom, la description et la couleur d’arrière-plan de l’étiquette.

Le nom est obligatoire, mais la description et la couleur sont facultatives. Le nom respecte la casse, ne peut pas dépasser 80 caractères et doit être unique au sein du compte. Bien que la couleur soit facultative, si vous ne la spécifiez pas, le service choisit une couleur aléatoire pour vous. Vous pouvez spécifier la couleur à l’aide d’un nombre hexadécimal de trois octets sous la forme #RRGGBB (par exemple, CB0400) ou de l’un des 16 noms de couleurs connus tels que rouge, jaune et aqua. Si vous spécifiez une couleur, vous devez spécifier une description, mais il peut s’agir d’une chaîne vide.

L’exemple suivant montre trois façons d’appeler la createLabel méthode .

function main() {

    AdsApp.createLabel("foo");
    AdsApp.createLabel("bar", "a descriptive description", "aqua");
    AdsApp.createLabel("foo foo", "", "#FF0000");

}

Répertorier les étiquettes d’un compte

Pour obtenir une liste d’étiquettes dans un compte, utilisez la méthode labels . Vous pouvez filtrer la liste par nom de l’étiquette à l’aide des opérateurs de chaîne standard tels que =, CONTAINS et STARTS_WITH.

function main() {

    // Gets all the labels in the account
    var accountLabels = AdsApp.labels()
        .get();  
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets all the labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account
    accountLabels = AdsApp.labels()
        .withLimit(15)
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .withLimit(15)
        .get();

    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    while (accountLabels.hasNext()){
        var label = accountLabels.next();
    }

}

Appliquer une étiquette à un mot clé

Les étiquettes ne sont utiles que si vous les appliquez à des entités telles que des mots clés. Pour appliquer une étiquette à un mot clé, utilisez la méthode applyLabel de l’mot clé. Vous pouvez appliquer un maximum de 50 étiquettes à un mot clé. La méthode prend comme entrée le nom de l’étiquette. Le nom de l’étiquette respecte la casse, doit exister dans le compte et doit être unique dans le mot clé.

L’exemple suivant montre comment ajouter des étiquettes à un mot clé, répertorier les étiquettes de l’mot clé et supprimer des étiquettes d’un mot clé.

function main() {

    // Get a keyword to add labels to
    var keyword = AdsApp.keywords().withIds(["12345"]).get().next();

    // Print the keyword's existing labels
    var labels = keyword.labels().get();
    printLabels(labels);

    // Add labels to the keyword
    keyword.applyLabel("foo");
    keyword.applyLabel("foo foo");
    keyword.applyLabel("bar");

    // Print the new list of labels
    labels = keyword.labels().get();
    printLabels(labels);

    // Remove labels from the keyword
    keyword.removeLabel("foo");
    keyword.removeLabel("bar");

    // Print the new list of labels
    labels = keyword.labels().get();
    printLabels(labels);

}

function printLabels(labels) {
    Logger.log(`keyword has ${labels.totalNumEntities()} labels`);
    
    while (labels.hasNext()){
        var label = labels.next();

        Logger.log(`name: ${label.getName()}
            description: ${label.getDescription()}
            color: ${label.getColor()}\n\n`);
    }
}

Obtenir des mots clés qui contiennent l’une des étiquettes spécifiées

Pour obtenir des mots clés qui contiennent des noms d’étiquette spécifiques, utilisez la méthode withCondition() de l’objet KeywordSelector. Utilisez le nom de colonne LabelNames pour filtrer par noms d’étiquette. Vous pouvez spécifier un tableau d’un ou plusieurs noms. Les noms respectent la casse, doivent correspondre exactement et doivent exister dans le compte. Vous pouvez appliquer les opérateurs suivants :

• CONTAINS_ALL : sélectionne le mot clé s’il contient toutes les étiquettes spécifiées
• CONTAINS_ANY : sélectionne le mot clé s’il contient l’une des étiquettes spécifiées
• CONTAINS_NONE : sélectionne le mot clé s’il ne contient aucune des étiquettes spécifiées

Notez que si l’étiquette n’existe pas dans le compte, le sélecteur échoue et retourne une erreur.

function main() {

    var keywords = AdsApp.keywords()
        .withCondition('LabelNames CONTAINS_ANY ["foo", "bar"]')
        .get();
    
    while (keywords.hasNext()){
        var keyword = keywords.next();

        var labels = keyword.labels().get();

        while (labels.hasNext()) {
            var label = labels.next();
        }
    }

}