Datums- und Uhrzeitangaben verwenden

In Verbindung mit Google Ads-Skripts werden oft Datums- und Uhrzeitangaben verwendet. Zu den häufigsten Anwendungsfällen gehören das Abrufen von Berichten für einen bestimmten Zeitraum, das Planen von Kampagnen oder Anzeigengruppen für bestimmte Zeiten und die Ausgabe des Zeitpunkts der letzten Ausführung des Skripts in eine Tabelle. In diesem Leitfaden werden wichtige Konzepte, häufige Fallstricke und empfohlene Vorgehensweisen für die Verwendung von Datums- und Uhrzeitangaben in Google Ads-Skripts beschrieben.

Grundlegende Konzepte

Um Datums- und Uhrzeitangaben in Google Ads-Skripts zu nutzen, verwenden Sie das integrierte Datumsobjekt ("date") von JavaScript. Ein solches Objekt steht für einen ganz bestimmten Zeitpunkt. Es gibt verschiedene Möglichkeiten, ein neues Datumsobjekt zu erstellen:

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

Neuen Skriptnutzern ist oft nicht ganz klar, wie Zeitzonen von Datumsobjekten behandelt werden. Datumsobjekte stehen nicht für die Uhrzeit in einer einzelnen Zeitzone. Im Snippet oben nehmen einige Nutzer beispielsweise fälschlicherweise an, dass date nur in einer Zeitzone gültig ist, nämlich in der Zeitzone mit einer Zeitverschiebung von -5 Stunden, die für die Erstellung verwendet wurde. In dieser falschen Ansicht müsste date konvertiert werden, damit es in anderen Zeitzonen verwendet werden kann.

Tatsächlich steht ein Datumsobjekt jedoch für einen ganz bestimmten Zeitpunkt, der von der Zeitzone unabhängig ist. Auch wenn in diesem Augenblick auf den Uhren in verschiedenen Zeitzonen eine andere Uhrzeit angezeigt wird, handelt es sich um denselben Zeitpunkt. Betrachten Sie zum Beispiel dieses 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);

Hinweis: Bei JavaScript wird ein Datumsobjekt intern als Anzahl der Millisekunden seit dem 1. Januar 1970 (UTC) dargestellt.

Da ein Datumsobjekt für einen ganz bestimmten Zeitpunkt steht, muss es nicht für die verschiedenen Zeitzonen konvertiert werden. Stattdessen kann es als String dargestellt werden, der für eine bestimmte Zeitzone formatiert ist.

Verwenden Sie Utilities.formatDate(date, timeZone, format), um ein Datum als String mit einem bestimmten Format und einer bestimmten Zeitzone zu rendern. Beispiel:

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 diesen Beispielen wird die Zeitzone direkt mithilfe einer Zeitzonen-ID angegeben. Mit AdsApp.currentAccount().getTimeZone() können Sie die Zeitzone des Google Ads-Kontos abrufen, über das Ihr Skript ausgeführt wird.

Häufige Stolperfallen

Standardzeitzone bei der Erfassung eines Datumsobjekts

Wenn ein Datumsobjekt direkt mit Logger.log() protokolliert wird, wird es mit einem Standardformat und einer Standardzeitzone gerendert. Beispiel:

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

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

Die Standardzeitzone ist PST (Los Angeles) – unabhängig davon, welche Zeitzone für das Google Ads-Konto festgelegt ist. Wenn das Datumsobjekt zu Logging- oder anderen Zwecken als String mit einem benutzerdefinierten Format und einer benutzerdefinierten Zeitzone gerendert werden soll, verwenden Sie immer Utilities.formatDate(date, timeZone, format).

Standardzeitzone beim Erstellen eines Datumsobjekts

Wenn Sie mithilfe eines Strings ohne Zeitverschiebung ein Datumsobjekt erstellen, wird PST (Los Angeles) als Zeitzone verwendet – unabhängig davon, welche Zeitzone für das Google Ads-Konto festgelegt ist. Beispiel:

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

Wenn Sie ein Datumsobjekt mit einem String erstellen, geben Sie immer einen Zeitzonenversatz an, damit das Datumsobjekt den gewünschten Zeitpunkt repräsentiert.

Standardzeitzone in Datumsobjektmethoden

Für JavaScript-Datumsobjekte gibt es mehrere Methoden, die eine Standardzeitzone voraussetzen. Beispiele:

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

Dies umfasst auch die set___()-Entsprechungen dieser Methoden (z. B. setMonth()) und getTimezoneOffset().

In Google Ads-Skripts ist die Standardzeitzone PST (Los Angeles) – unabhängig davon, welche Zeitzone für das Google Ads-Konto festgelegt ist. Daher sollten Sie diese Methoden generell nicht verwenden, es sei denn, Ihr Google Ads-Konto befindet sich in dieser Zeitzone.

Wenn Sie das Jahr, den Monat, das Datum, den Tag, die Stunden oder die Minuten eines Datumsobjekts in der Zeitzone Ihres Kontos abrufen möchten, verwenden Sie Utilities.formatDate(date, timeZone, format) mit einem Format, das den gewünschten Teil des Datums oder der Uhrzeit angibt, und AdsApp.currentAccount().getTimeZone(), um die Zeitzone Ihres Kontos abzurufen.

Datumsobjekt auf der Grundlage eines formatierten Datumsstrings erstellen

Sie können ein Datumsobjekt erstellen, indem Sie einen formatierten Datumsstring an den Datumskonstruktor übergeben. Beispiel:

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

Der Konstruktor kann nur bestimmte Datumsstringformate parsen. Damit der Datumsstring korrekt geparst wird, geben Sie ihn immer im Format MMMM dd, yyyy HH:mm:ss Z an.

So erstellen Sie beispielsweise ein Datumsobjekt für 12:00 Uhr heute in der Zeitzone des aktuellen Kontos:

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

Verwenden Sie das Muster „z“ nicht zum Erstellen von Datumsstrings, die an einen Datumskonstruktor übergeben werden, da der Konstruktor ihn nicht immer parsen kann. Verwenden Sie nur das Z-Muster.

Datumsberechnungen

Bei einigen Skripts müssen einfache Berechnungen für Datumsangaben angestellt werden, etwa um das Datum zu finden, das X Tage vor oder nach dem angegebenen Datum liegt. Verwenden Sie für Datumsberechnungen getTime(). Wenn getTime() für ein Datumsobjekt aufgerufen wird, wird die Anzahl der Millisekunden seit Beginn des 1. Januar 1970 (UTC) zurückgegeben. Sie können diesen Wert berechnen und dann den neuen Wert mit setTime() auf ein Datumsobjekt anwenden. Alternativ können Sie ihn beim Erstellen eines neuen Datumsobjekts als Parameter angeben.

Beispiel:

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

In diesem Beispiel liegt yesterday genau 24 Stunden vor.

Berichterstellung

Beim Abrufen eines Berichts mit AdsApp.search() müssen für die GAQL-Abfrage Datumsangaben im Format yyyy-MM-dd angegeben werden. 2021-06-30 wäre beispielsweise der 30. Juni 2021.

Außerdem müssen für die Methode getStatsFor(), die für viele Google Ads-Skriptobjekte verfügbar ist, Datumsangaben im selben Format angegeben werden. Verwenden Sie Utilities.formatDate(date, timeZone, format), um ein Datumsobjekt in diesem Format zu formatieren.

Beispielcode, mit dem ein Bericht für die Zeit vor 24 bis 72 Stunden abgerufen wird:

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

Tabellen

Bei Google Ads-Skripts wird die Ausgabe oft in eine Tabelle geschrieben, etwa im Fall von Datumsobjekten. Wenn Sie eine Zelle in einer Tabelle festlegen, indem Sie ein Datumsobjekt übergeben, werden diese Daten auf der Grundlage der Zeitzone der Tabelle ausgewertet. Angenommen, wir haben eine Tabelle, deren Zeitzone auf Pacific Time eingestellt ist:

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

Der Wert in A1 lautet „17-Feb-21 10:00:00“.

Um sicherzustellen, dass Datumsobjekte wie erwartet in eine Tabelle geschrieben werden, verwenden Sie für die Tabelle die Zeitzone Ihres Google Ads-Kontos:

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

Sie können die Zeit einer Tabelle auch manuell festlegen.