Como usar datas e horários

Os scripts do Google Ads geralmente precisam trabalhar com datas e horários. Entre os casos de uso comuns estão a recuperação de relatórios de um período específico, a programação de campanhas ou grupos de anúncios para veiculação em horários específicos e a geração de uma planilha com o horário da última execução do script. Este guia descreve conceitos importantes, armadilhas comuns e abordagens recomendadas ao trabalhar com datas e horas 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 JavaScript. Um objeto de data JavaScript representa um momento particular no tempo. Existem vários modos 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, 2021 13:00:00 -0500');

// Create a copy of an existing date object.
let copy = new Date(date);

Os novos usuários de scripts geralmente ficam confusos com o modo como os objetos de data lidam com os fusos horários. Uma maneira natural, mas incorreta de pensar em um objeto de data, é como o horário de um relógio em um único fuso horário. Por exemplo, no snippet acima, alguns usuários presumem incorretamente que date é válido apenas em um fuso horário, ou seja, o fuso com uma diferença de -5 horas que foi usada para criá-lo. Nesse caso, date precisaria ser "convertido" para ser usado em outros fusos horários.

O modo correto de ver um objeto de data é como um momento particular no tempo independente de qualquer fuso horário. Embora um determinado horário seja mostrado de forma diferente nos relógios de diferentes fusos horários, é o mesmo momento. Por exemplo, considere este snippet:

// Create two date objects with different times and timezone offsets.
const date1 = new Date('February 17, 2021 13:00:00 -0500');
const date2 = new Date('February 17, 2021 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);

Observação :internamente, JavaScript representa um objeto de data como o número de milissegundos desde 1o de janeiro de 1970 (UTC).

Como um objeto de data representa um momento particular no tempo, ele não precisa ser "convertido" em diferentes fusos horários. Pelo contrário, ele pode ser processado como uma string formatada para um fuso horário específico.

Para renderizar uma data como uma string com um formato e um fuso horário específicos, use Utilities.formatDate(date, timeZone, format). Exemplo:

const date = new Date('February 17, 2021 13:00:00 -0500');

// February 17, 2021 13:00:00 -0500
console.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2021 10:00:00 -0800
console.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2021-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 está executando seu script, use AdsApp.currentAccount().getTimeZone().

Dificuldades comuns

Fuso horário padrão ao registrar um objeto de data

Quando um objeto de data é registrado diretamente usando Logger.log(), ele é renderizado usando um formato e fuso horário padrão. Exemplo:

const date = new Date('February 17, 2021 13:00:00 -0500');

// Wed Feb 17 10:00:00 GMT-08:00 2021
console.log(date);

O fuso horário padrão é o dos Estados Unidos/Los Angeles (horário do Pacífico), independentemente 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 geração de registros ou outros fins, use sempre Utilities.formatDate(date, timeZone, format).

Fuso horário padrão ao criar um objeto de data

Quando você cria um objeto de data usando uma string que não faz o deslocamento de fuso horário, ele será considerado Estados Unidos/Los_Angeles (horário do Pacífico), independentemente do fuso horário associado à conta do Google Ads. Exemplo:

// Create a date without specifying the timezone offset.
const date = new Date('February 17, 2021 13:00:00');

// Wed Feb 17 13:00:00 GMT-08:00 2021
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 desejado.

Fuso horário padrão nos métodos do objeto de data

Os objetos de data JavaScript têm vários métodos que pressupõem um fuso horário padrão, como:

• getFullYear()
• getMonth()
• getDate()
• getDay()
• getHours()
• getMinutes()

Isso também inclui os equivalentes de 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), independentemente do fuso horário associado à conta do Google Ads. Portanto, a menos que sua conta do Google Ads esteja nesse fuso horário, evite o uso desses métodos.

Para conferir o ano, o mês, a data, o dia, as horas ou os 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 encontrar 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. Exemplo:

const date = new Date('February 17, 2021 13:00:00 -0500');

O criador é capaz de analisar apenas determinados formatos de strings de data. Para garantir que a string de data seja analisada corretamente, sempre a forneça no formato MMMM dd, yyyy HH:mm:ss Z.

Por exemplo, para criar 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 data, já que 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 fazer operações matemáticas de datas, use getTime(). Chamar getTime() em um objeto de data retorna o número de milissegundos desde o início de 1o de janeiro de 1970 (UTC). Faça cálculos com esse valor e aplique 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 se refere a 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, 2021-06-30 seria 30 de junho de 2021).

Da mesma forma, o método getStatsFor() disponível em muitos objetos de script do Google Ads exige que as datas sejam especificadas no mesmo formato. Use Utilities.formatDate(date, timeZone, format) para definir 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. Quando você define uma célula em uma planilha por meio de um objeto de data, o fuso horário da planilha é usado para interpretar essa data. Por exemplo, suponha que temos uma planilha cujo fuso horário esteja definido como o Horário do Pacífico:

// Suppose today is February 17, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

O valor em A1 será 17-fev-21 10:00:00.

Para garantir a gravação dos objetos de data na planilha conforme esperado, defina o fuso horário da planilha de modo que ele coincida com o fuso horário da sua conta do Google Ads:

spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());

Também é possível definir o horário de uma planilha manualmente.