A menudo, las secuencias de comandos de Google Ads deben trabajar con fechas y horas. Entre los casos de uso comunes, se incluyen la recuperación de informes para un período específico, la programación de campañas o grupos de anuncios para que se publiquen en momentos específicos, y la salida a una hoja de cálculo de la hora en que se ejecutó la secuencia de comandos por última vez. En esta guía, se describen conceptos importantes, errores comunes y enfoques recomendados cuando se trabaja con fechas y horas en las secuencias de comandos de Google Ads.
Conceptos básicos
Para trabajar con fechas y horas en las secuencias de comandos de Google Ads, usa el objeto de fecha integrado de JavaScript. Un objeto de fecha de JavaScript representa un momento determinado. Existen varias formas de crear un objeto de fecha nuevo:
// 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);
Los usuarios nuevos de Scripts suelen confundirse con la forma en que los objetos de fecha manejan las zonas horarias. Una forma natural, pero incorrecta de pensar en un objeto de fecha es como la hora de un reloj en una sola zona horaria. Por ejemplo, en el fragmento anterior, algunos usuarios suponen por error que date solo es válido en una zona horaria, es decir, la zona horaria con una desviación de -5 horas que se usó para crearla. En esa vista equivocada, date debería “convertirse” para usarse en otras zonas horarias.
En cambio, la forma correcta de pensar en un objeto de fecha es como un momento particular independiente de cualquier zona horaria. Aunque un momento en particular se muestre de manera diferente en relojes de diferentes zonas horarias, es el mismo momento. Por ejemplo, considera este fragmento:
// 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);
Como un objeto de fecha representa un momento específico en el tiempo, no es necesario que se lo "convierta" entre zonas horarias. En su lugar, se puede renderizar como una cadena con formato para una zona horaria específica.
Para renderizar una fecha como una cadena con un formato y una zona horaria en particular, usa Utilities.formatDate(date, timeZone,
format).
Por ejemplo:
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\''));
En estos ejemplos, se especificó la zona horaria directamente con un ID de zona horaria. Para recuperar la zona horaria asociada con la cuenta de Google Ads que ejecuta la secuencia de comandos, usa AdsApp.currentAccount().getTimeZone().
Errores comunes
Zona horaria predeterminada cuando se registra un objeto de fecha
Cuando se registra directamente un objeto de fecha con Logger.log(), se renderiza con un formato y una zona horaria predeterminados. Por ejemplo:
const date = new Date('February 17, 2021 13:00:00 -0500');
// Wed Feb 17 10:00:00 GMT-08:00 2021
console.log(date);
La zona horaria predeterminada es America/Los_Angeles (hora del Pacífico), independientemente de la zona horaria asociada con la cuenta de Google Ads. Si deseas renderizar el objeto de fecha como una cadena con un formato y una zona horaria personalizados para el registro o para otros fines, usa siempre Utilities.formatDate(date, timeZone,
format).
Zona horaria predeterminada cuando se crea un objeto de fecha
Cuando creas un objeto de fecha con una cadena que no proporciona un desplazamiento de zona horaria, se supone que la zona horaria es America/Los_Angeles (hora del Pacífico), independientemente de la zona horaria asociada a la cuenta de Google Ads. Por ejemplo:
// 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);
Cuando crees un objeto de fecha con una cadena, siempre incluye una compensación de zona horaria para asegurarte de que el objeto de fecha represente el momento que realmente deseas.
Zona horaria predeterminada en los métodos de objetos de fecha
Los objetos de fecha de JavaScript tienen varios métodos que suponen una zona horaria predeterminada, como los siguientes:
getFullYear()getMonth()getDate()getDay()getHours()getMinutes()
Esto también incluye los equivalentes set___() de estos métodos (por ejemplo, setMonth()) y getTimezoneOffset().
En las secuencias de comandos de Google Ads, la zona horaria predeterminada es America/Los_Angeles (hora del Pacífico), independientemente de la zona horaria asociada con la cuenta de Google Ads. Por lo tanto, a menos que tu cuenta de Google Ads esté en este huso horario, por lo general, debes evitar usar estos métodos.
Para obtener el año, el mes, la fecha, el día, las horas o los minutos de un objeto de fecha en la zona horaria de tu cuenta, usa Utilities.formatDate(date, timeZone,
format) con un formato que especifique la parte de la fecha o la hora que deseas y usa AdsApp.currentAccount().getTimeZone() para obtener la zona horaria de tu cuenta.
Cómo crear un objeto de fecha a partir de una cadena de fecha con formato
Para crear un objeto de fecha, pasa una cadena de fecha con formato al constructor de fecha. Por ejemplo:
const date = new Date('February 17, 2021 13:00:00 -0500');
El constructor solo puede analizar ciertos formatos de cadenas de fecha. Para asegurarte de que la cadena de fecha se analice correctamente, siempre proporciónala en el formato MMMM dd, yyyy
HH:mm:ss Z.
Por ejemplo, para construir un objeto de fecha para el mediodía de hoy en la zona horaria de la cuenta actual, haz lo siguiente:
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);
No uses el patrón "z" para crear cadenas de fecha que se pasarán a un constructor de fecha, ya que el constructor no siempre podrá analizarlas. Usa solo el patrón "Z".
Cálculos de fecha
Algunas secuencias de comandos deben realizar operaciones matemáticas simples con fechas, como encontrar una fecha X días antes o después de una fecha determinada. Cuando realices operaciones matemáticas con fechas, usa getTime().
Llamar a getTime() en un objeto de fecha muestra la cantidad de milisegundos desde principios del 1 de enero de 1970 UTC. Puedes realizar cálculos matemáticos con este valor y, luego, aplicar el valor nuevo a un objeto de fecha con setTime() o proporcionarlo como parámetro cuando creas un objeto de fecha nuevo.
Por ejemplo:
const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);
En este ejemplo, yesterday es exactamente hace 24 horas.
Informes
Cuando se recupera un informe con AdsApp.search(), la consulta de GAQL requiere que las fechas se especifiquen en el formato yyyy-MM-dd (por ejemplo, 2021-06-30 sería el 30 de junio de 2021).
Del mismo modo, el método getStatsFor() disponible en muchos objetos de secuencias de comandos de Google Ads requiere que las fechas se especifiquen en el mismo formato. Usa Utilities.formatDate(date, timeZone,
format) para dar este formato a un objeto de fecha.
Por ejemplo, para recuperar un informe de hace uno a tres días, sigue estos pasos:
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'));
Hojas de cálculo
Las secuencias de comandos de Google Ads suelen escribir resultados en una hoja de cálculo, incluidos los objetos de fecha. Cuando configuras una celda en una hoja de cálculo mediante el paso de un objeto de fecha, se usa la zona horaria de la hoja de cálculo para interpretar esa fecha. Por ejemplo, supongamos que tenemos una hoja de cálculo cuya zona horaria está configurada en la hora del Pacífico:
// Suppose today is February 17, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
El valor en A1 será 17/feb/21 10:00:00.
Para garantizar que los objetos de fecha se escriban en una hoja de cálculo como esperas, configura la zona horaria de la hoja de cálculo para que coincida con la zona horaria de tu cuenta de Google Ads:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
También puedes configurar la hora de una hoja de cálculo manualmente.