Pour discuter de nos produits et nous faire part de vos commentaires, rejoignez le canal Discord officiel Google Ads sur le serveur de la communauté Google Advertising and Measurement.

Cette page a été traduite par l'API Cloud Translation.

Utilisation des dates et des heures

Les scripts Google Ads doivent souvent fonctionner avec des dates et des heures. Les cas d'utilisation courants incluent la récupération de rapports pour une période spécifique, la programmation de la diffusion de campagnes ou de groupes d'annonces à des heures spécifiques, et l'exportation dans une feuille de calcul de l'heure à laquelle le script a été exécuté pour la dernière fois. Ce guide décrit les concepts importants, les pièges courants et les approches recommandées lorsque vous travaillez avec des dates et des heures dans les scripts Google Ads.

Concepts fondamentaux

Pour utiliser des dates et des heures dans les scripts Google Ads, utilisez l'objet Date intégré de JavaScript. Un objet de date JavaScript représente un moment précis. Il existe plusieurs façons de créer un objet de 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);

Les nouveaux utilisateurs de Scripts sont souvent déroutés par la façon dont les objets de date gèrent les fuseaux horaires. Une façon naturelle, mais incorrecte de considérer un objet date est de le voir comme l'heure sur une horloge dans un seul fuseau horaire. Par exemple, dans l'extrait ci-dessus, certains utilisateurs supposent à tort que date n'est valide que dans un seul fuseau horaire, à savoir celui avec un décalage de -5 heures qui a été utilisé pour le créer. Dans cette vue erronée, date devrait être "converti" pour être utilisé dans d'autres fuseaux horaires.

En revanche, la bonne façon de considérer un objet de date est de le voir comme un moment précis, indépendant de tout fuseau horaire. Bien qu'un moment précis soit affiché différemment sur les horloges de différents fuseaux horaires, il s'agit du même moment. Prenons l'exemple de l'extrait suivant :

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

Étant donné qu'un objet date représente un moment précis, il n'a pas besoin d'être "converti" en fonction des fuseaux horaires. Au lieu de cela, il peut être affiché sous forme de chaîne mise en forme pour un fuseau horaire spécifique.

Pour afficher une date sous forme de chaîne avec un format et un fuseau horaire spécifiques, utilisez Utilities.formatDate(date, timeZone, format). Par exemple : 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\''));

Ces exemples spécifient le fuseau horaire directement à l'aide d'un ID de fuseau horaire. Pour récupérer le fuseau horaire associé au compte Google Ads qui exécute votre script, utilisez AdsApp.currentAccount().getTimeZone().

Écueils les plus courants

Voici quelques pièges courants concernant les dates.

Fuseau horaire par défaut lors de la journalisation d'un objet de date

Lorsqu'un objet de date est enregistré directement à l'aide de Logger.log(), il est affiché à l'aide d'un format et d'un fuseau horaire par défaut. Exemple :

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

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

Le fuseau horaire par défaut est America/Los_Angeles (heure du Pacifique), quel que soit le fuseau horaire associé au compte Google Ads. Si vous souhaitez afficher l'objet de date sous forme de chaîne à l'aide d'un format et d'un fuseau horaire personnalisés pour la journalisation ou d'autres fins, utilisez toujours Utilities.formatDate(date, timeZone, format).

Fuseau horaire par défaut lors de la création d'un objet de date

Lorsque vous créez un objet de date à l'aide d'une chaîne qui ne fournit pas de décalage de fuseau horaire, le fuseau horaire est supposé être America/Los_Angeles (heure du Pacifique), quel que soit le fuseau horaire associé au compte Google Ads. Exemple :

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

Lorsque vous créez un objet de date à l'aide d'une chaîne, incluez toujours un décalage de fuseau horaire pour vous assurer que l'objet de date représente le moment précis que vous souhaitez.

Fuseau horaire par défaut dans les méthodes d'objet de date

Les objets de date JavaScript comportent plusieurs méthodes qui supposent un fuseau horaire par défaut, par exemple :

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

Cela inclut également les équivalents set___() de ces méthodes (par exemple, setMonth()) et getTimezoneOffset().

Dans les scripts Google Ads, le fuseau horaire par défaut est America/Los_Angeles (heure du Pacifique), quel que soit le fuseau horaire associé au compte Google Ads. Par conséquent, à moins que votre compte Google Ads ne soit dans ce fuseau horaire, vous devriez généralement éviter d'utiliser ces méthodes.

Pour obtenir l'année, le mois, la date, le jour, les heures ou les minutes d'un objet de date dans le fuseau horaire de votre compte, utilisez Utilities.formatDate(date, timeZone, format) avec un format spécifiant la partie de la date ou de l'heure que vous souhaitez, et utilisez AdsApp.currentAccount().getTimeZone() pour obtenir le fuseau horaire de votre compte.

Créer un objet date à partir d'une chaîne de date mise en forme

Vous pouvez créer un objet de date en transmettant une chaîne de date formatée au constructeur de date. Exemple :

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

Le constructeur ne peut analyser que certains formats de chaînes de date. Pour vous assurer que votre chaîne de date est analysée correctement, fournissez-la toujours au format MMMM dd, yyyy HH:mm:ss Z.

Par exemple, pour construire un objet de date pour midi aujourd'hui dans le fuseau horaire du compte actuel :

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

N'utilisez pas le modèle "z" pour créer des chaînes de date qui seront transmises à un constructeur de date, car le constructeur ne pourra pas toujours les analyser. N'utilisez que le motif "Z".

Calculs de dates

Certains scripts doivent effectuer des calculs simples avec des dates, par exemple pour trouver une date X jours avant ou après une date donnée. Lorsque vous effectuez des calculs de date, utilisez getTime(). L'appel de getTime() sur un objet de date renvoie le nombre de millisecondes écoulées depuis le début du 1er janvier 1970 UTC. Vous pouvez effectuer des calculs sur cette valeur, puis appliquer la nouvelle valeur à un objet de date à l'aide de setTime() ou en la fournissant en tant que paramètre lors de la création d'un objet de date.

Exemple :

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

Dans cet exemple, yesterday correspond exactement à 24 heures.

Rapports

Lorsque vous récupérez un rapport à l'aide de AdsApp.search(), la requête GAQL exige que les dates soient spécifiées au format yyyy-MM-dd (par exemple, 2025-06-30 correspond au 30 juin 2025).

De même, la méthode getStatsFor() disponible sur de nombreux objets de scripts Google Ads exige que les dates soient spécifiées dans le même format. Utilisez Utilities.formatDate(date, timeZone, format) pour mettre en forme un objet de date dans ce format.

Par exemple, pour récupérer un rapport datant d'un à trois jours :

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

Feuilles de calcul

Les scripts Google Ads écrivent souvent des données de sortie dans une feuille de calcul, y compris des objets de date. Lorsque vous définissez une cellule dans une feuille de calcul en transmettant un objet de date, le fuseau horaire de la feuille de calcul est utilisé pour interpréter cette date. Par exemple, supposons que nous disposions d'une feuille de calcul dont le fuseau horaire est défini sur "Heure du Pacifique" :

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

La valeur de la cellule A1 sera "17-Feb-25 10:00:00".

Pour vous assurer que les objets de date sont écrits dans une feuille de calcul comme vous le souhaitez, définissez le fuseau horaire de la feuille de calcul sur celui de votre compte Google Ads :

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

Vous pouvez également définir manuellement l'heure d'une feuille de calcul.