Exemplos de scripts para gerir palavras-chave

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

Adicionar palavras-chave

Para adicionar uma palavra-chave, primeiro obtenha o grupo de anúncios ao qual pretende adicionar a palavra-chave. Utilize o objeto AdGroupSelector para selecionar o grupo de anúncios. A utilização do withIds método proporciona um melhor desempenho do que transmitir o nome do grupo de anúncios no withCondition método .

Em seguida, chame o novo métodoKeywordBuilder do grupo de anúncios para obter um construtor que utilize para especificar as propriedades da palavra-chave. A única propriedade que tem de especificar é o texto da palavra-chave (consulte o withText método ). O texto deve incluir o tipo de correspondência (aspas para tipo de correspondência de expressão, parênteses retos para o tipo de correspondência exato, nada para o tipo de correspondência largo).

Se não especificar um valor CPC, este será predefinido para o valor CPC do grupo de anúncios. Por predefinição, o estado da palavra-chave está ativado.

Chamar o método do build construtor cria a palavra-chave de forma assíncrona; Os scripts adicionam a palavra-chave em algum momento antes de o script terminar ou se chamar um dos métodos da operação de compilação. Para obter informações sobre este processo, consulte O que é um construtor?

function main() {
    // The ID of the ad group to add the keywords to.
    // IDs in Scripts are string integers.
    var adGroupId = 'AD GROUP ID GOES HERE';  
    var adGroup = getAdGroup(adGroupId);

    // Keywords to add. Update as appropriate.
    var keywords = [];
    keywords.push({
        text : "keyword 1",
        cpc : 1.25,
        finalUrl : 'http://www.example.com'
    });
    keywords.push({
        text : "keyword 2",
        cpc : 1.5,
        finalUrl : 'http://www.example.com'
    });

    var operations = [];

    if (adGroup != null)
    {
        for (var keyword of keywords) {
            var operation = addKeyword(
                adGroup, 
                keyword.text, 
                keyword.cpc, 
                keyword.finalUrl);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve ad group, " + adGroupId);
    }

    checkBuildStatus(operations, keywords);
}

// Get the ad group using its ID.
function getAdGroup(id) {
    var iterator = AdsApp.adGroups()
        .withIds([id])
        .get();

    // Return the ad group if it exists; otherwise, null.
    if (iterator.hasNext()) {
        return iterator.next();
    }
    else {
        return null;
    }
}

// Add the keyword to the specified ad group.
function addKeyword(adGroup, text, cpc, finalUrl) {

    return adGroup.newKeywordBuilder()
        .withText(text)
        .withCpc(cpc)
        .withFinalUrl(finalUrl)
        .build();
}

// Check the keyword's build status.
function checkBuildStatus(operations, keywords) {

    for (var i = 0; i < operations.length; i++) {
        if (!operations[i].isSuccessful()) {
            for (var error of operations[i].getErrors()) {
                Logger.log(`Failed to add, ${keywords[i].text}. Error: ${error}`);
            }
        }
    }
}

Colocar uma palavra-chave em pausa

Quando adiciona uma palavra-chave, o respetivo estado é Ativado por predefinição. Para colocar a palavra-chave em pausa, chame o método da pause palavra-chave. Para determinar o estado da palavra-chave, chame as palavras-chave isEnabled e isPaused os métodos.

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';
    var keywordText = 'KEYWORD TEXT GOES HERE';

    var iterator = AdsApp.keywords()
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    while (iterator.hasNext()) {
        var keyword = iterator.next();
        keyword.pause();
    }
}

Obter todas as palavras-chave num grupo de anúncios

Para obter todas as palavras-chave num grupo de anúncios, chame primeiro o método do keywords objeto AdsApp para obter o seletor. Utilize o withCondition método para especificar o grupo de anúncios e a campanha. Em seguida, chame o método do get seletor para obter um iterador que utiliza para iterar através da lista de palavras-chave. Para determinar o número de palavras-chave no iterador, chame o método do totalNumEntities iterador.

Se tiver acesso aos IDs de palavra-chave, utilize-os em alternativa. A utilização de IDs para obter entidades proporciona um melhor desempenho. Em vez de utilizar o withCondition método de filtro, utilize o withIds método . Por exemplo, withIds(['12345']). Existem limites no número de entidades que pode obter através de IDs.

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';

    var iterator = AdsApp.keywords()
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
        
    while (iterator.hasNext()) {
        var keyword = iterator.next();
    }
}

Obter todas as palavras-chave numa conta

Existe um limite para o número de palavras-chave que os Scripts podem devolver para uma conta. O limite é indefinido e pode ser alterado. O exemplo seguinte mostra como pode lidar com casos em que uma conta tem demasiadas palavras-chave. O exemplo tenta obter primeiro todas as palavras-chave ao nível da conta. Se isso falhar devido ao erro "Existem demasiadas entidades", tenta fazer várias chamadas para obter palavras-chave por campanha, uma vez que normalmente existem menos entidades ao nível da campanha.

Para obter informações sobre como utilizar a palavra-chave de lucro , veja Utilizar a palavra-chave de lucro ao obter grandes conjuntos de entidades.

function* getEntities() {
    const applyConditions = _ => _
        .withCondition('CampaignStatus = ENABLED')
        .withCondition('AdGroupStatus = ENABLED')
        .withCondition('Status = ENABLED')
        .withCondition("CombinedApprovalStatus = DISAPPROVED");

    try {
        // Get the account's keywords. 
        const keywords = applyConditions(AdsApp.keywords()).get();

        while (keywords.hasNext()) {
            yield keywords.next();
        }
    } catch (e) {
        if (!e.message.startsWith('There are too many entities')) {
            throw e;
        }

        // If there are too many keywords at the account level,
        // get keywords by campaigns under the account.
        const campaigns = AdsApp.campaigns().get();

        while (campaigns.hasNext()) {
            const campaign = campaigns.next();

            const keywords = applyConditions(campaign.keywords()).get();

            while (keywords.hasNext()) {
                yield keywords.next();
            }
        }
    }
}

Obter dados de desempenho de uma palavra-chave

Para obter as métricas de desempenho de uma palavra-chave, chame o método getStats da palavra-chave. Quando obtém a palavra-chave, tem de especificar o intervalo de datas dos dados de métricas que pretende. Pode especificar o intervalo de datas com um literal predefinido, como LAST_MONTH ou HOJE, ou uma data de início e de fim. Para especificar o intervalo de datas, utilize um dos forDateRange métodos quando selecionar a palavra-chave (consulte KeywordSelector).

Para obter uma lista das métricas a que pode aceder, veja o objeto Estatísticas .

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';
    var keywordText = 'KEYWORD TEXT GOES HERE';

    // Get the keyword. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.keywords()
        .forDateRange('LAST_WEEK')
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    // If the keyword is found, log some metrics.
    if (iterator.hasNext()) {
        var keyword = iterator.next();
        var metrics = keyword.getStats(); // Gets the performance metrics.
    }
}

Atualize o valor da oferta de uma palavra-chave.

Para obter um exemplo que mostra como atualizar o valor da oferta de uma palavra-chave, consulte Chamar serviços Google.