Las secuencias de comandos de Google Ads a menudo necesitan trabajar con fechas y horas. Entre los casos de uso comunes, se incluyen recuperar informes para un período específico, programar campañas o grupos de anuncios para que se publiquen en horarios específicos y generar en una hoja de cálculo 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, 2025 13:00:00 -0500');
// Create a copy of an existing date object.
let copy = new Date(date);
Los usuarios nuevos de secuencias de comandos 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 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 determinado, independientemente de cualquier zona horaria. Aunque un momento determinado 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 time zone 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);
Como un objeto de fecha representa un momento determinado, no es necesario "convertirlo" en diferentes zonas horarias. En cambio, se puede renderizar como una cadena con formato para una zona horaria determinada.
Para renderizar una fecha como una cadena con un formato y una zona horaria determinados, 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 con 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 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 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 time zone 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 que deseas.
Zona horaria predeterminada en los métodos de 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 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 esta zona horaria, 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
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 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, 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. Solo usa el patrón "Z".
Cálculos de fecha
Algunas 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 fecha, 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 recuperas un informe con
AdsApp.search(),
la consulta 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 resultados en una hoja de cálculo, incluidos los objetos de fecha. Cuando se establece 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, establece 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 establecer la hora de una hoja de cálculo de forma manual.