Per discutere e fornire feedback sui nostri prodotti, unisciti al canale Discord ufficiale di Google Ads nel server della community di Google Advertising and Measurement.

Questa pagina è stata tradotta dall'API Cloud Translation.

Gestione di date e ore

Gli script Google Ads spesso devono gestire date e orari. I casi d'uso comuni includono il recupero di report per un intervallo di date specifico, la pianificazione di campagne o gruppi di annunci da pubblicare 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 lavora con date e ore negli script Google Ads.

Concetti di base

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

// 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 Apps Script spesso non sanno come gli oggetti data gestiscono i fusi orari. Un modo naturale ma errato di pensare a un oggetto data è come l'ora su un orologio in un unico fuso orario. Ad esempio, nello snippet precedente, alcuni utenti presuppongono 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.

Il modo corretto di pensare a un oggetto data è come a un momento specifico nel tempo, indipendente da qualsiasi fuso orario. Anche se un determinato momento viene mostrato in modo diverso sugli orologi di fusi orari diversi, si tratta dello stesso momento. Ad esempio, considera questo snippet:

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

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

Per eseguire il rendering di una data come stringa con un formato e un fuso orario particolari, 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 specificano 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

Ecco alcuni problemi comuni che si verificano con le date.

Fuso orario predefinito durante la registrazione di un oggetto data

Quando registri direttamente un oggetto data 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 eseguire il rendering dell'oggetto data 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 data

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

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

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

Fuso orario predefinito nei metodi degli oggetti data

Gli oggetti data 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 data 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 data da una stringa di data formattata

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

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

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

Ad esempio, per creare un oggetto data 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 data che verranno trasmesse a un costruttore di date, in quanto il costruttore non sarà sempre in grado di analizzarle. Utilizza solo il pattern "Z".

Calcoli con le date

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

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 corrisponde al 30 giugno 2025).

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

Ad esempio, per recuperare un report di 1-3 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 data. Quando imposti una cella in un foglio di lavoro passando un oggetto data, il fuso orario del foglio di lavoro viene utilizzato per interpretare la data. Ad esempio, supponiamo di avere un foglio di lavoro il cui fuso orario è impostato su Pacific Time:

// 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 data vengano scritti in un foglio di lavoro come previsto, imposta il fuso orario del foglio di lavoro in modo che corrisponda a quello del tuo account Google Ads:

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

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