Las secuencias de comandos de Google Ads suelen tener que indicar fechas y horas. Algunos casos de uso comunes 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 ejecuten en momentos específicos, y el envío a una hoja de cálculo en el momento 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, utiliza el objeto de fecha integrado de JavaScript. Un objeto de fecha de JavaScript representa un momento específico en el tiempo. Existen varias formas de crear un nuevo objeto de fecha:
// 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 de nuevas secuencias de comandos 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 erróneamente que date es válido solo en una zona horaria, es decir, la zona horaria con un desplazamiento de -5 horas que se usó para crearlo. En esa vista errónea, date debería "convertirse" para poder usarlo en otras zonas horarias.
En cambio, la forma correcta de pensar en un objeto de fecha es como un momento en particular independiente de cualquier zona horaria. Aunque un momento específico se muestra de manera diferente en los relojes de distintas 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);
Dado que un objeto de fecha representa un momento determinado en la hora, no es necesario "convertirlo" en distintas zonas horarias. En su lugar, se puede procesar como una string que tiene formato para una zona horaria en particular.
Para renderizar una fecha como una string con un formato y una zona horaria determinados, 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 especifica la zona horaria directamente con un ID de zona horaria. Para recuperar la zona horaria asociada con la cuenta de Google Ads en la que se 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 string con un formato y zona horaria personalizados para el registro o para otros fines, siempre usa Utilities.formatDate(date, timeZone,
format).
Zona horaria predeterminada cuando se crea un objeto de fecha
Cuando creas un objeto de fecha con una string que no proporciona un desplazamiento de zona horaria, se supone que la zona horaria corresponde a América/Los_Angeles (hora del Pacífico), independientemente de la zona horaria asociada con 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 debes incluir un desplazamiento de zona horaria para asegurarte de que el objeto de fecha represente el momento en que realmente deseas.
Zona horaria predeterminada en los métodos del objeto 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 de 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 se encuentre en esta zona horaria, generalmente debes evitar el uso de 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.
Crea 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 fechas. Por ejemplo:
const date = new Date('February 17, 2021 13:00:00 -0500');
El constructor solo puede analizar ciertos formatos de cadena de fecha. Para asegurarte de que tu cadena de fecha se analice correctamente, siempre proporciónala en el formato MMMM dd, yyyy
HH:mm:ss Z.
Por ejemplo, a fin de construir un objeto de fecha para el mediodía de hoy en la zona horaria de la cuenta actual:
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. Solo usa el patrón “Z”.
Matemáticas de fecha
Algunas secuencias de comandos necesitan realizar cálculos matemáticos simples con fechas, como buscar una fecha X días antes o después de una fecha determinada. Cuando realices cálculos de fechas, usa getTime().
Si llamas a getTime() en un objeto de fecha, se muestra la cantidad de milisegundos desde el comienzo del 1 de enero de 1970 UTC. Puedes realizar cálculos matemáticos en este valor y, luego, aplicar el valor nuevo a un objeto de fecha con setTime() o proporcionarlo como parámetro cuando crees 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 secuencia de comandos de Google Ads requiere que las fechas se especifiquen en el mismo formato. Usa Utilities.formatDate(date, timeZone,
format) para dar formato a un objeto de fecha en este formato.
Por ejemplo, para recuperar un informe de hace uno a tres días:
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 pasas un objeto de fecha para establecer una celda en una hoja de cálculo, 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 según 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 asegurarte de 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 de tu cuenta de Google Ads:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
También puedes configurar la hora de una hoja de cálculo de forma manual.