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 intervalo de fechas específico, la programación de campañas o grupos de anuncios para que se publiquen en horarios específicos y la generación de una hoja de cálculo con la hora en la que se ejecutó el script 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 particular. 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, 2025 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 controlan las zonas horarias. Una forma natural, pero incorrecta, de pensar en un objeto de fecha es como la hora en un reloj en una sola zona horaria. Por ejemplo, en el fragmento anterior, algunos usuarios suponen erróneamente que date solo es válido 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 usarse en otras zonas horarias.
En cambio, la forma correcta de pensar en un objeto de fecha es como un momento particular en el tiempo, independiente de cualquier zona horaria. Aunque un momento en particular se muestra de manera diferente en los 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, 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);
Dado que un objeto de fecha representa un momento particular en el tiempo, no es necesario "convertirlo" entre zonas horarias. En cambio, se puede renderizar como una cadena con formato para una zona horaria en particular.
Para renderizar una fecha como una cadena con un formato y una zona horaria particulares, usa Utilities.formatDate(date, timeZone, format).
Por ejemplo:
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\''));
En estos ejemplos, se especificó la zona horaria directamente con un ID de zona horaria.
Para recuperar la zona horaria asociada a la cuenta de Google Ads que ejecuta tu secuencia de comandos, usa AdsApp.currentAccount().getTimeZone().
Errores comunes
Estos son algunos errores comunes que ocurren con las fechas.
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, 2025 13:00:00 -0500');
// Mon Feb 17 10:00:00 GMT-08:00 2025
console.log(date);
La zona horaria predeterminada es America/Los_Angeles (hora del Pacífico), independientemente de la zona horaria asociada a 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 cualquier otro propósito, siempre usa Utilities.formatDate(date, timeZone, format).
Zona horaria predeterminada al crear un objeto de fecha
Cuando se crea 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 con la cuenta de Google Ads. Por ejemplo:
// Create a date without specifying the timezone offset.
const date = new Date('February 17, 2025 13:00:00');
// Mon Feb 17 13:00:00 GMT-08:00 2025
console.log(date);
Cuando crees un objeto de fecha con una cadena, siempre incluye un desplazamiento de zona horaria para asegurarte de que el objeto de fecha represente el momento en el tiempo 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 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 a 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 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
Puedes crear un objeto de fecha pasando una cadena de fecha con formato al constructor de fecha. Por ejemplo:
const date = new Date('February 17, 2025 13:00:00 -0500');
El constructor solo puede analizar ciertos formatos de cadenas 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, 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 fechas, ya que el constructor no siempre podrá analizarlas. Solo usa el patrón en forma de "Z".
Cálculos de fechas
Algunos secuencias de comandos necesitan realizar cálculos matemáticos simples con fechas, como encontrar 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 transcurridos desde el comienzo del 1 de enero de 1970 UTC. Puedes realizar operaciones matemáticas con 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 recuperas un informe con AdsApp.search(), la consulta de GAQL requiere que las fechas se especifiquen en el formato yyyy-MM-dd (por ejemplo, 2025-06-30 sería el 30 de junio de 2025).
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 formato a un objeto de fecha en este formato.
Por ejemplo, para recuperar un informe de hace uno a tres días, haz lo siguiente:
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 la salida en una hoja de cálculo, incluidos los objetos de fecha. Cuando se configura una celda en una hoja de cálculo pasando 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á establecida en la hora del Pacífico:
// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
El valor en A1 será 17-feb-25 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 establecer la hora de una hoja de cálculo de forma manual.