Esempi di script per la gestione delle etichette

Le sezioni seguenti mostrano esempi di script che eseguono varie azioni sulle etichette.

Aggiungere etichette a un account

Per utilizzare le etichette, prima di tutto aggiungerle al proprio 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 utilizzando un numero esadecimale a tre byte nel formato #RRGGBB (ad esempio, CB0400) o uno dei 16 nomi di colore noti come 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, utilizzare il metodo delle etichette . È 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 applicate a entità come le parole chiave. Per applicare un'etichetta a una parola chiave, usare il metodo applyLabel della parola chiave. A una parola chiave possono essere applicate al massimo 50 etichette. Il metodo prende come input il nome dell'etichetta. Il nome dell'etichetta fa distinzione tra maiuscole e minuscole, deve essere presente 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 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 delle etichette specificate

Per ottenere parole chiave che contengono nomi di etichette specifici, utilizzare 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 ed essere presenti nell'account. È possibile applicare i seguenti operatori:

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

}