Esempi di script per la gestione dei gruppi di annunci

Le sezioni seguenti mostrano esempi di script che eseguono varie azioni sui gruppi di annunci.

Aggiungere gruppi di annunci

Per aggiungere un gruppo di annunci, fai in modo che sia la campagna a cui aggiungere il gruppo di annunci. Usare l'oggetto CampaignSelector per selezionare la campagna. L'utilizzo del withIds metodo consente di ottenere prestazioni migliori rispetto al passaggio del withCondition nome della campagna nel metodo.

Quindi, chiama il metodo newAdGroupBuilder della campagna per ottenere un generatore che usi per specificare le proprietà del gruppo di annunci. L'unica proprietà richiesta è il nome del gruppo di annunci (vedere il withName metodo), che deve essere univoco all'interno della campagna. Se non si specifica un valore CPC, per impostazione predefinita viene utilizzato l'importo minimo dell'offerta per la valuta dell'account. È necessario specificare la lingua solo se la campagna non la specifica; In caso contrario, eredita il valore della lingua della campagna. Per impostazione predefinita, lo stato del gruppo di annunci è sospeso.

Chiamando il metodo del generatore, il gruppo di build annunci viene creato in modo asincrono; Script aggiunge il gruppo di annunci in un momento precedente al termine dello script o se si chiama uno dei metodi dell'operazione di compilazione. Per informazioni su questo processo, vedere Che cos'è un builder?

function main() {
    // The ID of the campaign to add the ad groups to.
    // IDs in Scripts are string integers.
    var campaignId = 'CAMPAIGN ID GOES HERE';  
    var campaign = getCampaign(campaignId);

    // Ad groups to add.
    var adGroups = [];
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 2.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });
    adGroups.push({
        name : 'AD GROUP NAME GOES HERE',
        cpc : 1.25,
        language : 'English' // Required if the campaign doesn't specify a language
    });

    var operations = [];

    if (campaign != null)
    {
        for (var adGroup of adGroups) {
            var operation = addAdGroup(
                campaign, 
                adGroup.name, 
                adGroup.cpc, 
                adGroup.language);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve campaign, " + campaignId);
    }

    checkBuildStatus(operations, adGroups);
}

// Get the campaign using its ID.
function getCampaign(id) {
    var iterator = AdsApp.campaigns()
        .withIds([id])
        .get();

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

// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to 
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {

    return campaign.newAdGroupBuilder()
        .withName(name)
        .withCpc(cpc)
        .withLanguage(language)
        .build();
}

// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {

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

Ottenere tutti i gruppi di annunci

Per ottenere tutti i gruppi di annunci in un account, chiamare prima il metodo dell'oggetto adGroupsAdsApp per ottenere il selettore. Quindi, chiama il metodo del get selettore per ottenere un iteratore che usi per scorrere l'elenco dei gruppi di annunci. Poiché nell'esempio non viene specificato alcun filtro, lo strumento di selezione restituisce tutti i gruppi di annunci dell'account. Per determinare il numero di gruppi di annunci nell'iteratore, chiamare il metodo dell'iteratore totalNumEntities .

function main() {
    // Gets all ad groups in the account.
    var iterator = AdsApp.adGroups().get();
    
    // Iterates through the list of ad groups and logs 
    // each ad group's name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

Ottenere un gruppo di annunci in base al nome

Per ottenere un gruppo di annunci in base al nome, chiamare prima il metodo dell'oggetto adGroupsAdsApp per ottenere il selettore. Il selettore contiene diversi metodi di filtro utilizzati per filtrare l'elenco dei gruppi di annunci. Utilizzare il withCondition metodo per filtrare i gruppi di annunci in base a un nome specifico del gruppo di annunci. Si noti che gli operandi e gli operatori fanno distinzione tra maiuscole e minuscole.

Quindi, chiama il metodo del get selettore per ottenere l'iteratore. I nomi dei gruppi di annunci all'interno di una campagna sono univoci, ma è possibile che più campagne abbiano gruppi di annunci con lo stesso nome. Per questo motivo, se si filtra solo in base al nome, l'iteratore potrebbe contenere più gruppi di annunci.

Se si desidera ottenere un gruppo di annunci in base al nome da una campagna specifica, includere un withCondition metodo che specifichi il nome della campagna (CampaignName = '<campaignnamegoeshere>').

function main() {
    // The name of the ad group to get.
    var adGroupName = 'AD GROUP NAME GOES HERE';

    // Get the ad groups with the specified name.
    var iterator = AdsApp.adGroups()
          .withCondition(`Name = '${adGroupName}'`)
          .get();

    // Need a loop because multiple campaigns can have 
    // an ad group with the same name.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

Ottenere un gruppo di annunci in base all'ID

Se hai accesso all'ID del gruppo di annunci, usalo al suo posto. L'uso degli ID per ottenere entità offre prestazioni migliori. Invece di usare il withCondition metodo di filtro, usare il withIds metodo. Ad esempio, withIds(['12345']).

function main() {
    var adGroupId = '12345';

    var iterator = AdsApp.adGroups()
        .withIds([adGroupId])
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

Ottenere un gruppo di annunci per nome da una campagna specifica

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

    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
    }
}

Recuperare i dati sul rendimento di un gruppo di annunci

Per ottenere le metriche sulle prestazioni di un gruppo di annunci, chiamare il metodo getStats del gruppo di annunci. Quando si ottiene il gruppo di annunci, è 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 OGGI, oppure una data di inizio e di fine. Per specificare l'intervallo di date, utilizzare uno dei metodi quando si seleziona il gruppo di forDateRange annunci (vedere AdGroupSelector).

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

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

    // Get the ad group. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.adGroups()
        .forDateRange('LAST_WEEK')
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
    
    // If the ad group is found, log some metrics.
    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        var metrics = adGroup.getStats(); // Gets the performance metrics.
    }
}

Sospendere un gruppo di annunci

Quando si aggiunge un gruppo di annunci, lo stato è Sospeso per impostazione predefinita. Per abilitare il gruppo di annunci, chiamare il metodo del gruppo di enable annunci. Per modificare lo stato del gruppo di annunci su Sospeso, chiama il metodo del gruppo di pause annunci. Per determinare lo stato del gruppo di annunci, chiamare i metodi e isPausedisRemoved i metodi del gruppo di isEnabledannunci.

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

    // Get the ad group. 
    var iterator = AdsApp.adGroups()
        .withCondition(`Name = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    if (iterator.hasNext()) {
        var adGroup = iterator.next();
        adGroup.pause();
    }
}