Como usar datas e horários

Os scripts do Google AdWords 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 da veiculação de campanhas ou grupos de anúncios em horários específicos e a geração de uma planilha com informações sobre o horário em que um 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 AdWords.

Conceitos básicos

Para trabalhar com datas e horários nos scripts do Google AdWords, 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.
var now = new Date();

// Create a date object for a past date and time using a formatted string.
var date = new Date('February 17, 2016 13:00:00 -0500');

// Create a copy of an existing date object.
var 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. Um modo natural (porém incorreto) de ver um objeto de data é como se fosse o horário em um relógio em um fuso horário único. Por exemplo, no snippet acima, alguns usuários diriam, de modo equivocado, que date é válido apenas em um fuso horário, ou seja, o fuso horário com -5 horas de diferença que foi usado para criá-lo. Nessa visão equivocada, date teria de 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.
var date1 = new Date('February 17, 2016 13:00:00 -0500');
var date2 = new Date('February 17, 2016 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.
Logger.log(date1.getTime() == date2.getTime());

// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
Logger.log(date1 == date2);

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 processar uma data como uma string com um formato e um fuso horário específicos, use Utilities.formatDate(date, timeZone, format). Por exemplo:

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

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

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

// 2016-02-17T18:00:00.000Z
Logger.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 AdWords que está executando seu script, use AdWordsApp.currentAccount().getTimeZone().

Armadilhas comuns

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

Quando você registra um objeto de data diretamente usando Logger.log(), ele é processado usando um formato e o fuso horário padrão. Por exemplo:

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

// Wed Feb 17 10:00:00 GMT-08:00 2016
Logger.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 AdWords. Se você quiser processar o objeto de data como uma string usando um formato e um fuso horário personalizados por motivos de registro ou com outras finalidades, 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, é considerado o fuso horário Estados Unidos/Los Angeles (horário do Pacífico), independentemente do fuso horário associado à conta do Google AdWords. Por exemplo:

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

// Wed Feb 17 13:00:00 GMT-08:00 2016
Logger.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 realmente represente o momento esperado.

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

Os objetos de data JavaScript têm vários métodos que usam um fuso horário padrão, incluindo getFullYear(), getMonth(), getDate(), getDay(), getHours() e getMinutes(), além dos equivalentes set___() deles, e getTimezoneOffet(). Nos scripts do Google AdWords, o fuso horário padrão é Estados Unidos/Los Angeles (horário do Pacífico), independentemente do fuso horário associado à conta do Google AdWords. Dessa forma, se sua conta do Google AdWords não estiver nesse fuso horário, você deverá evitar o uso desses métodos, de modo geral.

Para obter o ano, o mês, a data, o dia, as horas ou os minutos para um objeto de data no fuso horário da sua conta, use sempre Utilities.formatDate(date, timeZone, format) com um formato especificando a parte da data ou horário desejada. Use AdWordsApp.currentAccount().getTimeZone() para ver 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:

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

O criador é capaz de analisar apenas determinados formatos de strings de data. Para que sua string de data seja analisada corretamente, sempre forneça-a no formato MMMM dd, aaaa 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:

var now = new Date();
var timeZone = AdWordsApp.currentAccount().getTimeZone();
var noonString = Utilities.formatDate(now, timeZone,
                                      'MMMM dd, yyyy 12:00:00 Z')
var noon = new Date(noonString);

Não use o padrão "z" para criar strings de data que serão transmitidas para o criador de datas, pois nem sempre o criador será capaz de analisá-lo. Use somente 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 data, sempre use getTime(). A chamada de getTime() em um objeto de data retorna o número de milissegundos desde o início da contagem em 1º de janeiro de 1970 (UTC). É possível realizar operações matemáticas nesse valor e, em seguida, aplicar o novo valor ao objeto de data usando setTime() ou fornecendo-o como um parâmetro ao criar um novo objeto de data.

Por exemplo:

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

Nesse exemplo, yesterday corresponde exatamente ao período de 24 horas atrás.

Relatórios

Quando você recupera um relatório usando AdWordsApp.report(query, optArgs), a consulta AWQL requer datas especificadas como um número inteiro de oito dígitos (AAAAMMDD). Da mesma forma, o método getStatsFor() disponível em muitos objetos de scripts do Google AdWords requer datas especificadas como um número inteiro de oito dígitos. Use Utilities.formatDate(date, timeZone, format) para colocar um objeto de data nesse formato.

Por exemplo, para recuperar um relatório com informações de um a três dias atrás:

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
var to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);

var timeZone = AdWordsApp.currentAccount().getTimeZone();
var report = AdWordsApp.report(
  'SELECT CampaignName, Clicks ' +
  'FROM   CAMPAIGN_PERFORMANCE_REPORT ' +
  'DURING ' + Utilities.formatDate(from, timeZone, 'yyyyMMdd') + ','
            + Utilities.formatDate(to, timeZone, 'yyyyMMdd'));

Planilhas

Geralmente, os scripts do Google AdWords 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, digamos que exista uma planilha cujo fuso horário tenha sido definido como o horário do Pacífico:

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

O valor em A1 será 17-fev-16 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 AdWords:

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

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

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.