Gestione di date e ore

Spesso gli script Google Ads devono funzionare con date e orari. I casi d'uso comuni includono il recupero dei report per un intervallo di date specifico, la pianificazione di campagne o gruppi di annunci in modo che vengano eseguiti a orari specifici e l'invio su un foglio di lavoro dell'ora dell'ultima esecuzione dello script. Questa guida descrive concetti importanti, insidie comuni e approcci consigliati per l'uso di date e orari negli script di Google Ads.

Concetti di base

Per lavorare con date e orari negli script Google Ads, utilizza l'oggetto data incorporato di JavaScript. Un oggetto data JavaScript rappresenta un momento specifico. 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, 2021 13:00:00 -0500');

// Create a copy of an existing date object.
let copy = new Date(date);

Gli utenti dei nuovi script sono spesso confusi dal modo in cui gli oggetti con data gestiscono i fusi orari. Un modo naturale ma errato di pensare a un oggetto data è come l'ora di un orologio di un singolo fuso orario. Ad esempio, nello snippet precedente alcuni utenti presuppongono erroneamente che date sia valido solo in un fuso orario, ovvero quello con uno scarto di -5 ore utilizzato per crearlo. In questa visualizzazione erronea, date deve essere "convertito" per essere utilizzato in altri fusi orari.

Invece, il modo corretto per pensare a un oggetto data è un momento specifico nel tempo indipendente da qualsiasi fuso orario. Anche se un particolare momento viene mostrato in modo diverso sugli orologi di fusi orari diversi, Ad esempio, considera questo snippet:

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

Nota: internamente, JavaScript rappresenta un oggetto data come numero di millisecondi dal 1° gennaio 1970 (UTC).

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

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

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

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

Insidie comuni

Fuso orario predefinito durante il logging di un oggetto data

Quando si registra direttamente un oggetto data utilizzando Logger.log(), il rendering viene eseguito utilizzando un formato e un fuso orario predefiniti. Ad esempio:

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

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

Il fuso orario predefinito è America/Los_Angeles (fuso orario del Pacifico), indipendentemente dal fuso orario associato all'account Google Ads. Se vuoi visualizzare l'oggetto data come stringa utilizzando un formato e un fuso orario personalizzati per il logging 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 una differenza di fuso orario, si presume che il fuso orario sia America/Los_Angeles (fuso orario 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, 2021 13:00:00');

// Wed Feb 17 13:00:00 GMT-08:00 2021
console.log(date);

Quando crei un oggetto data utilizzando una stringa, includi sempre un offset di fuso orario per assicurarti che l'oggetto data rappresenti il momento effettivo che vuoi.

Fuso orario predefinito nei metodi dell'oggetto data

Gli oggetti data di JavaScript dispongono di 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 (fuso orario 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, generalmente dovresti evitare di utilizzare questi metodi.

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

Creazione di un oggetto data da una stringa di data formattata

Puoi creare un oggetto data passando una stringa di data formattata allo strumento di creazione delle date. Ad esempio:

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

Il costruttore può analizzare solo determinati formati di stringa di date. Per assicurarti che la stringa della data venga analizzata correttamente, forniscila sempre 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 date che verranno passate a un costruttore di date, poiché quest'ultimo non sarà sempre in grado di analizzarlo. Usa soltanto il pattern a "Z".

Calcolo delle date

Alcuni script devono eseguire semplici calcoli matematici con le date, ad esempio trovare una data X giorni prima o dopo una determinata data. Quando esegui i calcoli relativi alle date, utilizza getTime(). La chiamata di getTime() su un oggetto data restituisce il numero di millisecondi dall'inizio del 1° gennaio 1970 UTC. Puoi eseguire calcoli matematici su questo valore e poi 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.

Report

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

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

Ad esempio, per recuperare un report risalente a uno o tre giorni prima:

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 di Google Ads spesso scrivono l'output su 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 questa data. Ad esempio, supponiamo di avere un foglio di lavoro il cui fuso orario è impostato sul fuso orario del Pacifico:

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

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

Per assicurarti che gli oggetti con 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.