Acesso a conta única

Se você quiser acessar uma única conta de usuário, tudo começa com o objeto AdsApp .

Como devo proceder para aceder às entidades da minha conta?

Utilize AdsApp para aceder a todas as entidades na conta. O objeto contém um método seletor para cada tipo de entidade (por exemplo, campanhas, grupos de anúncios e palavras-chave). O método seletor retorna todas as entidades para esse tipo de entidade. Por exemplo, para obter todos os grupos de anúncios na conta, chame o adGroups() método.

    var iterator = AdsApp.adGroups().get();

Mas e se eu quiser uma entidade específica ou um subconjunto de entidades?

O seletor fornece diferentes maneiras de filtrar a lista de entidades. Você pode usar o método do withIds() seletor para obter entidades específicas por IDs ou pode usar withCondition() para especificar os critérios de seleção para selecionar as entidades. Os seletores para todos os tipos de entidade, exceto listas de palavras-chave negativas, fornecem a capacidade de filtrar a lista de entidades.

Utilize a notação de pontos para adicionar múltiplos filtros entre si. Se especificar vários filtros, estes são tratados como uma operação E. O seletor devolve apenas as entidades que correspondem a todas as condições.

Para obter todos os grupos de anúncios em uma campanha, use o método para especificar o withCondition() nome da campanha.

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

Para obter uma lista de condições e operadores que você pode usar para filtrar a lista de entidades, consulte o método do withCondition() seletor. Por exemplo, para obter uma lista de condições do grupo de anúncios, consulte o método withCondition do seletor do grupo de anúncios.

Para obter um grupo de anúncios por ID, use o withIds() método para especificar o grupo de anúncios a ser obtido.

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

Ou pode obter o grupo de anúncios pelo nome.

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

Para obter mais informações sobre seletores, consulte O que são seletores?

Como devo proceder para usar o seletor para iterar pela lista filtrada de entidades?

Não. O seletor apenas define as entidades que pretende obter. Para realmente obter as entidades, você usa um iterador. Para obter o iterador, você chama o método do get() seletor.

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

Use um loop while simples para iterar sobre a lista de entidades.

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        
        // Do something with the entity
    }

Para obter mais informações sobre iteradores, consulte O que são iteradores?

Como devo proceder para obter dados de desempenho para uma entidade?

A maioria das entidades permite solicitar dados de desempenho, se disponíveis. Mas primeiro você precisa dizer aos scripts o intervalo de datas para os dados de desempenho quando especificar o seletor. Para especificar um intervalo de datas, utilize um literal predefinido, como ONTEM ou LAST_MONTH ou utilize uma data de início e de fim. Para obter mais informações, consulte forDateRange(string dateRange) e forDateRange(Object dateFrom, Object dateTo).

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

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        var stats = adGroup.getStats();
    }

Você também precisa especificar um intervalo de datas se especificar uma coluna de dados de desempenho em um método do withCondition() seletor. Por exemplo, se pretender apenas grupos de anúncios com uma CTR superior a 0,22%, tem de especificar um intervalo de datas.

    var startDate = {year: 2018, month: 6, day: 3};
    var endDate = {year: 2018, month: 6, day: 13};

    var iterator = AdsApp.adGroups()
        .forDateRange(startDate, endDate)
        .withCondition("Ctr > 0.22")
        .get();

Como devo proceder para adicionar uma entidade?

Para adicionar uma entidade, use um objeto builder. Para obter um objeto do construtor, chame o método new* no objeto pai ao qual você está adicionando filhos. Por exemplo, para adicionar grupos de anúncios a uma campanha, chame o método da newAdGroupBuilder() campanha.

O objeto builder contém métodos para definir todas as propriedades do objeto que você pode especificar. Ele também inclui um build() método que você usa para criar a entidade. A seguir mostramos como criar um grupo de anúncios. (Para obter informações sobre como obter um objeto de campanha, consulte Obter uma campanha pelo nome.)

        var adGroupName = "My ad group";
        var endDate = {year: 2018, month: 6, day: 13};
        var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};

        var adGroupOperation = campaign.newAdGroupBuilder()
            .withName(adGroupName)
            .withStatus('ENABLED')
            .withLanguage('English')
            .withBiddingStrategy('MANUAL_CPC')
            .withCpc(1.2)
            .withCustomParameters(customParameters)
            .withEndDate(endDate)
            .build();

O build método retorna um objeto de operação, que você pode usar para verificar se os scripts criaram com êxito a entidade. A seguir mostra o padrão típico de chamadas. Chame o getResult método somente se desejar acessar as propriedades da nova entidade.

    if (adGroupOperation.isSuccessful()) {
        var adGroup = adGroupOperation.getResult();

    }
    else {
        for (var error of adGroupOperation.getErrors()) {
            Logger.log(`${error}\n`);
        }
    }

Para obter mais detalhes sobre construtores e considerações de desempenho ao chamar os métodos de operação, consulte O que são construtores?

Como devo proceder para atualizar uma entidade?

Depois de usar um objeto builder para adicionar uma entidade, você usa os métodos da entidade para atualizar suas propriedades. O exemplo a seguir atualiza o valor do lance de CPC do grupo de anúncios.

    var ids = ["123456789"];
    var adGroups = AdsApp.adGroups()
        .withIds(ids)
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        adGroup.bidding().setCpc(2.5);
    }

Mas como posso saber se a atualização funcionou?

Se tentar atualizar uma propriedade com um valor inválido, o Scripts escreve um erro no registo de alterações, mas não gera uma exceção, pelo que o script continua em execução. Não obtenha a propriedade depois de atualizá-la para verificar se a propriedade contém o novo valor; Este procedimento afeta negativamente o desempenho.

function main() {
    var id = "123456789";
    var bidAmount = -2.5;  
    var keyword = getKeyword(id); 

    if (keyword != null) {
        keyword.bidding().setCpc(bidAmount);  // Bid is not set because bid amount is not valid
    }

}

function getKeyword(id) {
    var keywords = AdsApp.keywords()
        .withIds([id])
        .get();

    if (keywords.hasNext()) {
        return keywords.next();
    }
    else {
        return null;
    }    
}

Gravando no arquivo de log

Scripts fornece um arquivo de log para você escrever informações de rastreamento e depuração. Para obter informações, consulte Logs de alterações e logs de texto.

Passos seguintes