Esempi di script per la gestione delle etichette

Le sezioni seguenti illustrano esempi di script che eseguono varie azioni per le etichette.

Aggiungere etichette a un account

Per usare le etichette, aggiungerle prima all'account. È possibile aggiungere un massimo di 100.000 etichette a un account. Per aggiungere un'etichetta, usare il metodo createLabel . Il metodo accetta come input il nome, la descrizione e il colore di sfondo dell'etichetta.

Il nome è obbligatorio, ma la descrizione e il colore sono facoltativi. Il nome fa distinzione tra maiuscole e minuscole, non può superare gli 80 caratteri e deve essere univoco all'interno dell'account. Anche se il colore è facoltativo, se non lo si specifica, il servizio sceglie automaticamente un colore casuale. È possibile specificare il colore usando un numero esadecimale di tre byte nel formato #RRGGBB (ad esempio, CB0400) o uno dei 16 nomi di colore noti, ad esempio rosso, giallo e acqua. Se si specifica un colore, è necessario specificare una descrizione, ma potrebbe essere una stringa vuota.

Nell'esempio seguente vengono illustrati tre modi per chiamare il createLabel metodo .

function main() {

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

}

Elencare le etichette di un account

Per ottenere un elenco di etichette in un account, usare il metodo labels . È possibile filtrare l'elenco in base al nome dell'etichetta usando gli operatori stringa standard, ad esempio =, CONTAINS e 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();
    }

}

Applicare un'etichetta a una parola chiave

Le etichette sono utili solo se vengono applicate a entità come parole chiave. Per applicare un'etichetta a una parola chiave, usare il metodo applyLabel della parola chiave. È possibile applicare un massimo di 50 etichette a una parola chiave. Il metodo accetta come input il nome dell'etichetta. Il nome dell'etichetta fa distinzione tra maiuscole e minuscole, deve esistere nell'account e deve essere univoco all'interno della parola chiave .

Nell'esempio seguente viene illustrato come aggiungere etichette a una parola chiave, elencare le etichette della parola chiave e rimuovere le etichette da una parola chiave.

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`);
    }
}

Ottenere parole chiave che contengono una qualsiasi delle etichette specificate

Per ottenere parole chiave che contengono nomi di etichetta specifici, usare il metodo withCondition() dell'oggetto KeywordSelector. Usare il nome della colonna LabelNames per filtrare in base ai nomi delle etichette. È possibile specificare una matrice di uno o più nomi. I nomi fanno distinzione tra maiuscole e minuscole, devono corrispondere esattamente e devono esistere nell'account. È possibile applicare gli operatori seguenti:

• CONTAINS_ALL: seleziona la parola chiave se contiene tutte le etichette specificate
• CONTAINS_ANY: seleziona la parola chiave se contiene una delle etichette specificate
• CONTAINS_NONE: seleziona la parola chiave se non contiene nessuna delle etichette specificate

Si noti che se l'etichetta non esiste nell'account, il selettore ha esito negativo e restituisce un errore.

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();
        }
    }

}