Acesso a uma única conta
Se quiser aceder a uma única conta de utilizador, tudo começa com o objeto AdsApp .
Como devo proceder para aceder às entidades na minha conta?
Utilize AdsApp para aceder a todas as entidades na conta. O objeto contém um método de seletor para cada tipo de entidade (por exemplo, campanhas, grupos de anúncios e palavras-chave). O método do seletor devolve 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 formas de filtrar a lista de entidades. Pode utilizar o método do withIds() seletor para obter entidades específicas por IDs ou pode utilizar withCondition() para especificar os critérios de seleção para selecionar as entidades. Os seletores para todos os tipos de entidade, exceto para listas de palavras-chave negativas, fornecem a capacidade de filtrar a lista de entidades.
Utilize a notação de pontos para juntar vários filtros. Se especificar múltiplos 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 numa campanha, utilize o withCondition() método para especificar o 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 pode utilizar para filtrar a lista de entidades, veja o método do withCondition() seletor. Por exemplo, para obter uma lista das condições do grupo de anúncios, veja o método withCondition do seletor de grupo de anúncios.
Para obter um grupo de anúncios por ID, utilize o withIds() método para especificar o grupo de anúncios a obter.
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
Em alternativa, 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 utilizar o seletor para iterar através da lista filtrada de entidades?
Não tem. O seletor apenas define as entidades que pretende obter. Para obter as entidades, utilize um iterador. Para obter o iterador, chame o método do get() seletor.
var ids = ["123456789"];
var iterator = AdsApp.adGroups()
.withIds(ids)
.get();
Utilize um ciclo de tempo simples para iterar através da 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-lhe pedir dados de desempenho, se disponíveis. No entanto, primeiro tem de indicar aos Scripts o intervalo de datas dos 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, veja 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();
}
Também tem de especificar um intervalo de datas se especificar uma coluna de dados de desempenho no método de withCondition() um seletor. Por exemplo, se quiser apenas grupos de anúncios que tenham um CTR superior a 0,22 por cento, terá 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, utilize um objeto de construtor. Para obter um objeto de construtor, chame o método new* no objeto principal ao qual está a adicionar subordinados. Por exemplo, para adicionar grupos de anúncios a uma campanha, chame o método da newAdGroupBuilder() campanha.
O objeto do construtor contém métodos para definir todas as propriedades do objeto que tem permissão para especificar. Também inclui um build() método que utiliza para criar a entidade. O seguinte mostra 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 devolve um objeto de operação, que pode utilizar para verificar se os Scripts criaram a entidade com êxito. O seguinte mostra o padrão de chamada típico. Chame o getResult método apenas se quiser aceder às 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, veja O que são os construtores?
Como devo proceder para atualizar uma entidade?
Depois de utilizar um objeto de construtor para adicionar uma entidade, utilize os métodos da entidade para atualizar as respetivas propriedades. O exemplo seguinte atualiza o montante da oferta 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 que a atualização funcionou?
Se tentar atualizar uma propriedade com um valor inválido, os Scripts escrevem um erro no Registo de alterações, mas não gera uma exceção, pelo que o script continua a ser executado. Não obtenha a propriedade depois de atualizá-la para verificar se a propriedade contém o novo valor; esta ação 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;
}
}
Escrever no ficheiro de registo
Os scripts fornecem um ficheiro de registo para o qual pode escrever informações de rastreio e depuração. Para obter informações, consulte Alterar registos e registos de texto.