Exemplos de scripts para gerir etiquetas

As secções seguintes mostram exemplos de scripts que efetuam várias ações em relação a etiquetas.

Adicionar etiquetas a uma conta

Para utilizar etiquetas, primeiro adicione-as à sua conta. Pode adicionar um máximo de 100 000 etiquetas a uma conta. Para adicionar uma etiqueta, utilize o método createLabel . O método utiliza como entrada o nome, a descrição e a cor de fundo da etiqueta.

O nome é obrigatório, mas a descrição e a cor são opcionais. O nome é sensível a maiúsculas e minúsculas, não pode exceder os 80 carateres e tem de ser exclusivo na conta. Embora a cor seja opcional, se não a especificar, o serviço escolhe uma cor aleatória para si. Pode especificar a cor utilizando um número hexadecimal de três bytes no formulário #RRGGBB (por exemplo, CB0400) ou um dos 16 nomes de cores conhecidos, como vermelho, amarelo e aqua. Se especificar uma cor, tem de especificar uma descrição, mas pode ser uma cadeia vazia.

O exemplo seguinte mostra três formas de chamar o createLabel método .

function main() {

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

}

Listar as etiquetas de uma conta

Para obter uma lista de etiquetas numa conta, utilize o método de etiquetas . Pode filtrar a lista pelo nome da etiqueta com os operadores de cadeia padrão, tais como =, 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();
    }

}

Aplicar uma etiqueta a uma palavra-chave

As etiquetas só são úteis se as aplicar a entidades como palavras-chave. Para aplicar uma etiqueta a uma palavra-chave, utilize o método applyLabel da palavra-chave. Pode aplicar um máximo de 50 etiquetas a uma palavra-chave. O método utiliza como entrada o nome da etiqueta. O nome da etiqueta é sensível às maiúsculas e minúsculas, tem de existir na conta e tem de ser exclusivo na palavra-chave.

O exemplo seguinte mostra como adicionar etiquetas a uma palavra-chave, listar as etiquetas da palavra-chave e remover etiquetas de uma palavra-chave.

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

Obter palavras-chave que contenham qualquer uma das etiquetas especificadas

Para obter palavras-chave que contenham nomes de etiquetas específicos, utilize o método comCondition() do objeto KeywordSelector. Utilize o nome da coluna LabelNames para filtrar por nomes de etiquetas. Pode especificar uma matriz de um ou mais nomes. Os nomes são sensíveis a maiúsculas e minúsculas, têm de corresponder exatamente e têm de existir na conta. Pode aplicar os seguintes operadores:

• CONTAINS_ALL — seleciona a palavra-chave se esta contiver todas as etiquetas especificadas
• CONTAINS_ANY — seleciona a palavra-chave se esta contiver qualquer uma das etiquetas especificadas
• CONTAINS_NONE — seleciona a palavra-chave se não contiver nenhuma das etiquetas especificadas

Tenha em atenção que, se a etiqueta não existir na conta, o seletor falha e devolve um erro.

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

}