Gestione di date e ore

Gli script Google Ads spesso devono utilizzare date e orari. I casi d'uso comuni includono il recupero di report per un intervallo di date specifico, la pianificazione dell'esecuzione di campagne o gruppi di annunci in orari specifici e l'output in un foglio di lavoro dell'ora dell'ultima esecuzione dello script. Questa guida descrive concetti importanti, errori comuni e approcci consigliati quando si utilizzano date e orari negli script Google Ads.

Concetti di base

Per utilizzare date e orari negli script Google Ads, utilizza l'oggetto date integrato di JavaScript. Un oggetto date JavaScript rappresenta un momento specifico nel tempo. Esistono diversi modi per creare un nuovo oggetto date:

// 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);

I nuovi utenti di script spesso non sanno come gli oggetti date gestiscono i fusi orari. Un modo naturale ma errato di pensare a un oggetto date è come l'ora su un orologio in un singolo fuso orario. Ad esempio, nello snippet precedente, alcuni utenti presumono erroneamente che date sia valido solo in un fuso orario, ovvero il fuso orario con un offset di -5 ore utilizzato per crearlo. In questa visualizzazione errata, date dovrebbe essere "convertito" per essere utilizzato in altri fusi orari.

Invece, il modo corretto di pensare a un oggetto date è come a un momento specifico nel tempo, indipendente da qualsiasi fuso orario. Sebbene un momento specifico venga visualizzato in modo diverso sugli orologi in fusi orari diversi, è lo stesso momento. Ad esempio, prendi in considerazione questo snippet:

// 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);

Nota: internamente, JavaScript rappresenta un oggetto date come il numero di millisecondi dall'inizio del 1° gennaio 1970 UTC.

Poiché un oggetto date rappresenta un momento specifico nel tempo, non è necessario "convertirlo" tra i fusi orari. Può invece essere visualizzato come una stringa formattata per un fuso orario specifico.

Per visualizzare una data come stringa con un formato e un fuso orario specifici, utilizza Utilities.formatDate(date, timeZone, format). Ad esempio:

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\''));

Questi esempi hanno specificato il fuso orario direttamente utilizzando un ID fuso orario. Per recuperare il fuso orario associato all'account Google Ads che esegue lo script, utilizza AdsApp.currentAccount().getTimeZone().

Errori comuni

Di seguito sono riportati alcuni errori comuni che si verificano con le date.

Fuso orario predefinito durante la registrazione di un oggetto date

Quando registri direttamente un oggetto date utilizzando Logger.log(), viene visualizzato utilizzando un formato e un fuso orario predefiniti. Ad esempio:

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

// Mon Feb 17 10:00:00 GMT-08:00 2025
console.log(date);

Il fuso orario predefinito è America/Los_Angeles (ora del Pacifico), indipendentemente dal fuso orario associato all'account Google Ads. Se vuoi visualizzare l'oggetto date come stringa utilizzando un formato e un fuso orario personalizzati per la registrazione o altri scopi, utilizza sempre Utilities.formatDate(date, timeZone, format).

Fuso orario predefinito durante la creazione di un oggetto date

Quando crei un oggetto date utilizzando una stringa che non fornisce un offset del fuso orario , si presume che il fuso orario sia America/Los_Angeles (ora del Pacifico) indipendentemente dal fuso orario associato all'account Google Ads. Ad esempio:

// 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);

Quando crei un oggetto date utilizzando una stringa, includi sempre un offset del fuso orario per assicurarti che l'oggetto date rappresenti il momento nel tempo che desideri.

Fuso orario predefinito nei metodi dell'oggetto date

Gli oggetti date JavaScript hanno diversi metodi che presuppongono un fuso orario predefinito, ad esempio:

• getFullYear()
• getMonth()
• getDate()
• getDay()
• getHours()
• getMinutes()

Sono inclusi anche gli equivalenti set___() di questi metodi (ad esempio, setMonth()) e getTimezoneOffset().

Negli script Google Ads, il fuso orario predefinito è America/Los_Angeles (ora del Pacifico ), indipendentemente dal fuso orario associato all'account Google Ads. Pertanto, a meno che il tuo account Google Ads non si trovi in questo fuso orario, in genere dovresti evitare di utilizzare questi metodi.

Per ottenere l'anno, il mese, la data, il giorno, le ore o i minuti per un oggetto date nel fuso orario del tuo account, utilizza Utilities.formatDate(date, timeZone, format) con un formato che specifica la parte della data o dell'ora che ti interessa e utilizza AdsApp.currentAccount().getTimeZone() per ottenere il fuso orario del tuo account.

Creazione di un oggetto date da una stringa di data formattata

Puoi creare un oggetto date passando una stringa di data formattata al costruttore di date. Ad esempio:

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

Il costruttore può analizzare solo determinati formati di stringhe di date. Per assicurarti che la stringa di data venga analizzata correttamente, fornisci sempre il formato MMMM dd, yyyy HH:mm:ss Z.

Ad esempio, per creare un oggetto date per mezzogiorno di oggi nel fuso orario dell'account corrente:

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);

Non utilizzare il pattern "z" per creare stringhe di date che verranno passate a un costruttore di date, poiché il costruttore non sarà sempre in grado di analizzarle. Utilizza solo il pattern "Z".

Calcoli con le date

Alcuni script devono eseguire semplici calcoli con le date, ad esempio trovare una data X giorni prima o dopo una determinata data. Quando esegui calcoli con le date, utilizza getTime(). La chiamata di getTime() su un oggetto date restituisce il numero di millisecondi dall'inizio del 1° gennaio 1970 UTC. Puoi eseguire calcoli su questo valore, quindi applicare il nuovo valore a un oggetto date utilizzando setTime() o fornendolo come parametro durante la creazione di un nuovo oggetto date.

Ad esempio:

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

In questo esempio, yesterday è esattamente 24 ore fa.

Rapporti

Quando recuperi un report utilizzando AdsApp.search(), la query GAQL richiede che le date siano specificate nel formato yyyy-MM-dd (ad esempio, 2025-06-30 sarebbe il 30 giugno 2025).

Allo stesso modo, il metodo getStatsFor() disponibile su molti oggetti di script Google Ads richiede che le date siano specificate nello stesso formato. Utilizza Utilities.formatDate(date, timeZone, format) per formattare un oggetto date in questo formato.

Ad esempio, per recuperare un report da uno a tre giorni fa:

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'));

Fogli di lavoro

Gli script Google Ads spesso scrivono l'output in un foglio di lavoro, inclusi gli oggetti date. Quando imposti una cella in un foglio di lavoro passando un oggetto date, viene utilizzato il fuso orario del foglio di lavoro per interpretare la data. Ad esempio, supponiamo di avere un foglio di lavoro il cui fuso orario è impostato su Ora del Pacifico:

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

Il valore in A1 sarà 17-feb-25 10:00:00.

Per assicurarti che gli oggetti date vengano scritti in un foglio di lavoro come previsto, imposta il fuso orario del foglio di lavoro in modo che corrisponda al fuso orario del tuo account Google Ads:

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

Puoi anche impostare manualmente l'ora di un foglio di lavoro.