Os scripts do Google Ads geralmente precisam trabalhar com datas e horários. Os casos de uso comuns incluem a recuperação de relatórios para um período específico, o agendamento de campanhas ou grupos de anúncios para veiculação em horários específicos e a saída para uma planilha do horário em que o script foi executado pela última vez. Este guia descreve conceitos importantes, armadilhas comuns e abordagens recomendadas ao trabalhar com datas e horários nos scripts do Google Ads.
Conceitos básicos
Para trabalhar com datas e horários nos scripts do Google Ads, use o objeto de data integrado do JavaScript. Um objeto de data JavaScript representa um momento particular no tempo. Há várias maneiras de criar um novo objeto de data:
// Create a date object for the current date and time.
const now = new Date();
// Create a date object for a past date and time using a formatted string.
const date = new Date('February 17, 2025 13:00:00 -0500');
// Create a copy of an existing date object.
let copy = new Date(date);
Os novos usuários de scripts costumam ficar confusos sobre como os objetos de data processam fusos horários. Uma maneira natural, mas incorreta , de pensar em um objeto de data é como o horário em um relógio em um único fuso horário. Por exemplo, no snippet anterior, alguns usuários presumem erroneamente que date é válido apenas em um fuso horário, ou seja, o fuso horário com um deslocamento de -5 horas que foi usado para criá-lo. Nessa visão equivocada, date precisaria ser "convertido" para ser usado em outros fusos horários.
Em vez disso, a maneira correta de pensar em um objeto de data é como um momento específico no tempo, independente de qualquer fuso horário. Embora um momento específico seja mostrado de maneira diferente em relógios em fusos horários diferentes, ele é o mesmo momento. Por exemplo, considere este snippet:
// Create two date objects with different times and time zone offsets.
const date1 = new Date('February 17, 2025 13:00:00 -0500');
const date2 = new Date('February 17, 2025 10:00:00 -0800');
// getTime() returns the number of milliseconds since the beginning of
// January 1, 1970 UTC.
// True, as the dates represent the same moment in time.
console.log(date1.getTime() == date2.getTime());
// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
console.log(date1 == date2);
Como um objeto de data representa um momento específico no tempo, ele não precisa ser "convertido" em fusos horários. Em vez disso, ele pode ser renderizado como uma string formatada para um fuso horário específico.
Para renderizar uma data como uma string com um formato e fuso horário específicos, use
Utilities.formatDate(date, timeZone, format).
Por exemplo:
const date = new Date('February 17, 2025 13:00:00 -0500');
// February 17, 2025 13:00:00 -0500
console.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));
// February 17, 2025 10:00:00 -0800
console.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));
// 2025-02-17T18:00:00.000Z
console.log(Utilities.formatDate(date, 'Etc/GMT', 'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\''));
Esses exemplos especificaram o fuso horário diretamente usando um
ID de fuso horário.
Para recuperar o fuso horário associado à conta do Google Ads que executa o
script, use
AdsApp.currentAccount().getTimeZone().
Armadilhas comuns
Confira algumas armadilhas comuns que ocorrem com datas.
Fuso horário padrão ao registrar um objeto de data
Ao registrar diretamente um objeto de data usando Logger.log(), ele é renderizado usando um formato e fuso horário padrão. Por exemplo:
const date = new Date('February 17, 2025 13:00:00 -0500');
// Mon Feb 17 10:00:00 GMT-08:00 2025
console.log(date);
O fuso horário padrão é América/Los_Angeles (horário do Pacífico), independente do
fuso horário associado à conta do Google Ads. Se você quiser renderizar
o objeto de data como uma string usando um formato e fuso horário personalizados para registro ou
outros fins, sempre use
Utilities.formatDate(date, timeZone, format).
Fuso horário padrão ao criar um objeto de data
Ao criar um objeto de data usando uma string que não fornece um deslocamento de fuso horário, o fuso horário é considerado América/Los_Angeles (horário do Pacífico), independente do fuso horário associado à conta do Google Ads. Por exemplo:
// Create a date without specifying the time zone offset.
const date = new Date('February 17, 2025 13:00:00');
// Mon Feb 17 13:00:00 GMT-08:00 2025
console.log(date);
Ao criar um objeto de data usando uma string, sempre inclua um deslocamento de fuso horário para garantir que o objeto de data represente o momento em que você realmente quer.
Fuso horário padrão em métodos de objeto de data
Os objetos de data JavaScript têm vários métodos que assumem um fuso horário padrão, como:
getFullYear()getMonth()getDate()getDay()getHours()getMinutes()
Isso também inclui os equivalentes set___() desses métodos (por exemplo, setMonth()) e getTimezoneOffset().
Nos scripts do Google Ads, o fuso horário padrão é América/Los_Angeles (horário do Pacífico ), independente do fuso horário associado à conta do Google Ads. Portanto, a menos que sua conta do Google Ads esteja nesse fuso horário, geralmente evite usar esses métodos.
Para receber o ano, mês, data, dia, horas ou minutos de um objeto de data no
fuso horário da sua conta, use
Utilities.formatDate(date, timeZone, format)
com um formato que especifique a parte da data ou hora desejada e use
AdsApp.currentAccount().getTimeZone()
para receber o fuso horário da sua conta.
Criação de um objeto de data a partir de uma string de data formatada
Você pode criar um objeto de data transmitindo uma string de data formatada para o criador de datas. Por exemplo:
const date = new Date('February 17, 2025 13:00:00 -0500');
O construtor só pode analisar determinados formatos de string de data. Para garantir que a
string de data seja analisada corretamente, sempre forneça-a no formato MMMM dd, yyyy
HH:mm:ss Z.
Por exemplo, para construir um objeto de data para o meio-dia de hoje no fuso horário da conta atual:
const now = new Date();
const timeZone = AdsApp.currentAccount().getTimeZone();
const noonString = Utilities.formatDate(now, timeZone, 'MMMM dd, yyyy 12:00:00 Z');
const noon = new Date(noonString);
Não use o padrão "z" para criar strings de data que serão transmitidas a um construtor de datas, porque o construtor nem sempre poderá analisá-lo. Use apenas o padrão "Z".
Operações matemáticas da data
Alguns scripts precisam realizar operações matemáticas simples com as datas, como encontrar uma data X dias antes ou depois de outra data. Ao realizar operações matemáticas de data, use getTime().
Chamar getTime() em um objeto de data retorna o número de milissegundos desde o início de 1º de janeiro de 1970 UTC. Você pode realizar operações matemáticas nesse valor e, em seguida, aplicar o novo valor a um objeto de data usando setTime() ou fornecendo-o como um parâmetro ao criar um novo objeto de data.
Exemplo:
const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);
Neste exemplo, yesterday é exatamente 24 horas atrás.
Relatórios
Ao recuperar um relatório usando
AdsApp.search(),
a consulta GAQL exige que as datas sejam
especificadas no formato yyyy-MM-dd (por exemplo, 2025-06-30 seria
30 de junho de 2025).
Da mesma forma, o método getStatsFor() disponível em muitos objetos de scripts do Google Ads exige que as datas sejam especificadas no mesmo formato. Use
Utilities.formatDate(date, timeZone, format)
para formatar um objeto de data nesse formato.
Por exemplo, para recuperar um relatório com informações de um a três dias atrás:
const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
const to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);
const timeZone = AdsApp.currentAccount().getTimeZone();
const results = AdsApp.search(
'SELECT campaign.name, metrics.clicks' +
'FROM campaign ' +
'WHERE segments.date BETWEEN ' +
Utilities.formatDate(from, timeZone, 'yyyy-MM-dd') + ' AND ' +
Utilities.formatDate(to, timeZone, 'yyyy-MM-dd'));
Planilhas
Geralmente, os scripts do Google Ads gravam os resultados em uma planilha, incluindo os objetos de data. Ao definir uma célula em uma planilha transmitindo um objeto de data, o fuso horário da planilha é usado para interpretar essa data. Por exemplo, suponha que tenhamos uma planilha cujo fuso horário esteja definido como horário do Pacífico:
// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
O valor em A1 será 17-Feb-25 10:00:00.
Para garantir que os objetos de data sejam gravados em uma planilha conforme o esperado, defina o fuso horário da planilha para corresponder ao fuso horário da sua conta do Google Ads:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
Você também pode definir o horário de uma planilha manualmente.