Esempi di script per la gestione delle parole chiave

Le sezioni seguenti illustrano esempi di script che eseguono varie azioni sulle parole chiave.

Aggiungere parole chiave

Per aggiungere una parola chiave, ottenere prima il gruppo di annunci a cui aggiungere la parola chiave. Usare l'oggetto AdGroupSelector per selezionare il gruppo di annunci. L'uso del withIds metodo offre prestazioni migliori rispetto al passaggio del nome del gruppo di annunci nel withCondition metodo .

Chiamare quindi il metodo newKeywordBuilder del gruppo di annunci per ottenere un generatore usato per specificare le proprietà della parola chiave. L'unica proprietà che è necessario specificare è il testo della parola chiave (vedere il withText metodo ). Il testo deve includere il tipo di corrispondenza (virgolette per il tipo di corrispondenza frase, parentesi quadre per il tipo di corrispondenza esatta, niente per il tipo di corrispondenza generale).

Se non specifichi un valore CPC, per impostazione predefinita è il valore CPC del gruppo di annunci. Per impostazione predefinita, lo stato della parola chiave è abilitato.

La chiamata al metodo del build generatore crea la parola chiave in modo asincrono; Script aggiunge la parola chiave a un certo punto prima che lo script venga terminato o se si chiama uno dei metodi dell'operazione di compilazione. Per informazioni su questo processo, vedere Che cos'è un generatore?

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

Sospendere una parola chiave

Quando si aggiunge una parola chiave, il relativo stato è Abilitato per impostazione predefinita. Per sospendere la parola chiave, chiamare il metodo della pause parola chiave. Per determinare lo stato della parola chiave, chiamare i metodi e isPaused delle isEnabled parole chiave.

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

Ottenere tutte le parole chiave in un gruppo di annunci

Per ottenere tutte le parole chiave in un gruppo di annunci, chiamare innanzitutto il metodo dell'oggetto keywordsAdsApp per ottenere il selettore. Usa il withCondition metodo per specificare il gruppo di annunci e la campagna. Chiamare quindi il metodo del get selettore per ottenere un iteratore usato per scorrere l'elenco di parole chiave. Per determinare il numero di parole chiave nell'iteratore, chiamare il metodo dell'iteratore totalNumEntities .

Se si ha accesso agli ID parola chiave, usarli invece. L'uso degli ID per ottenere le entità offre prestazioni migliori. Anziché usare il withCondition metodo di filtro, usare il withIds metodo . Ad esempio, withIds(['12345']). Esistono limiti al numero di entità che è possibile recuperare usando gli ID.

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

Recupero di tutte le parole chiave in un account

Esiste un limite al numero di parole chiave che gli script possono restituire per un account. Il limite non è definito e può cambiare. Nell'esempio seguente viene illustrato come gestire i casi in cui un account contiene troppe parole chiave. L'esempio tenta di recuperare prima tutte le parole chiave a livello di account. Se l'errore non riesce a causa dell'errore "Ci sono troppe entità", tenta di effettuare più chiamate per recuperare le parole chiave per campagna, poiché in genere sono presenti meno entità a livello di campagna.

Per informazioni sull'uso della parola chiave yield , vedere Usare la parola chiave yield quando si ottengono set di entità di grandi dimensioni.

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

Ottenere i dati sulle prestazioni di una parola chiave

Per ottenere le metriche delle prestazioni di una parola chiave, chiamare il metodo getStats della parola chiave. Quando si ottiene la parola chiave, è necessario specificare l'intervallo di date dei dati delle metriche desiderati. È possibile specificare l'intervallo di date usando un valore letterale predefinito, ad esempio LAST_MONTH o TODAY, oppure una data di inizio e fine. Per specificare l'intervallo di date, usare uno dei forDateRange metodi quando si seleziona la parola chiave (vedere KeywordSelector).

Per un elenco delle metriche a cui è possibile accedere, vedere l'oggetto Stats .

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.
    }
}

Aggiornare il valore dell'offerta di una parola chiave.

Per un esempio che illustra come aggiornare il valore dell'offerta di una parola chiave, vedere Chiamata ai servizi Google.