Datums- und Uhrzeitangaben verwenden

In Verbindung mit Google Ads-Skripts werden oft Datums- und Uhrzeitangaben verwendet. Häufige Anwendungsfälle sind das Abrufen von Berichten für einen bestimmten Zeitraum, das Planen von Kampagnen oder Anzeigengruppen für bestimmte Zeiten und die Ausgabe der letzten Ausführungszeit des Skripts in einer Tabelle. In diesem Leitfaden werden wichtige Konzepte, häufige Fehler und empfohlene Ansätze für die Arbeit mit Datums- und Uhrzeitangaben in Google Ads-Skripts beschrieben.

Grundlegende Konzepte

Wenn Sie in Google Ads-Skripts mit Datums- und Uhrzeitangaben arbeiten möchten, verwenden Sie das integrierte Datumsobjekt von JavaScript. Ein solches Objekt steht für einen ganz bestimmten Zeitpunkt. Es gibt mehrere 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, 2025 13:00:00 -0500');

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

Neue Skriptnutzer sind oft verwirrt, wie Datumsobjekte Zeitzonen verarbeiten. Eine naheliegende, aber falsche Vorstellung von einem Datumsobjekt ist die Uhrzeit auf einer Uhr in einer einzelnen Zeitzone. Im Snippet oben gehen einige Nutzer beispielsweise fälschlicherweise davon aus, dass date nur in einer Zeitzone gültig ist, nämlich in der Zeitzone mit einem Offset von -5 Stunden, die zum Erstellen verwendet wurde. Nach dieser falschen Vorstellung müsste date „konvertiert“ werden, um in anderen Zeitzonen verwendet werden zu können.

Stattdessen ist die richtige Vorstellung von einem Datumsobjekt ein bestimmter Zeitpunkt unabhängig von einer Zeitzone. Obwohl ein bestimmter Zeitpunkt auf Uhren in verschiedenen Zeitzonen unterschiedlich angezeigt wird, ist es derselbe Zeitpunkt. Beispiel:

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

Hinweis: Intern stellt JavaScript ein Datumsobjekt als die Anzahl der Millisekunden seit dem 1. Januar 1970 (UTC) dar.

Da ein Datumsobjekt einen bestimmten Zeitpunkt darstellt, muss es nicht zwischen Zeitzonen „konvertiert“ werden. Stattdessen kann es als String gerendert 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, 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\''));

In diesen Beispielen wurde die Zeitzone direkt mit einer Zeitzonen-ID angegeben. Verwenden Sie AdsApp.currentAccount().getTimeZone(), um die Zeitzone abzurufen, die mit dem Google Ads-Konto verknüpft ist, in dem Ihr Skript ausgeführt wird.

Häufige Fehler

Im Folgenden finden Sie einige häufige Fehler, die bei Datumsangaben auftreten.

Standardzeitzone beim Protokollieren eines Datumsobjekts

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

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

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

Die Standardzeitzone ist „America/Los_Angeles“ (Pazifische Zeit), unabhängig von der Zeitzone, die mit dem Google Ads-Konto verknüpft ist. Wenn Sie das Datumsobjekt als String mit einem benutzerdefinierten Format und einer benutzerdefinierten Zeitzone für die Protokollierung oder andere Zwecke rendern möchten, verwenden Sie immer Utilities.formatDate(date, timeZone, format).

Standardzeitzone beim Erstellen eines Datumsobjekts

Wenn Sie ein Datumsobjekt mit einem String erstellen, der keinen Zeitzonen-Offset enthält, wird die Zeitzone „America/Los_Angeles“ (Pazifische Zeit) angenommen, unabhängig von der Zeitzone, die mit dem Google Ads-Konto verknüpft ist. Beispiel:

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

Wenn Sie ein Datumsobjekt mit einem String erstellen, fügen Sie immer einen Zeitzonen-Offset ein, damit das Datumsobjekt den gewünschten Zeitpunkt darstellt.

Standardzeitzone in Datumsobjektmethoden

JavaScript-Datumsobjekte haben mehrere Methoden, die eine Standardzeitzone annehmen, z. B.:

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

Dazu gehören auch die entsprechenden set___()-Methoden (z. B. setMonth()) und getTimezoneOffset().

In Google Ads-Skripts ist die Standardzeitzone „America/Los_Angeles“ (Pazifische Zeit), unabhängig von der Zeitzone, die mit dem Google Ads-Konto verknüpft ist. Sofern sich Ihr Google Ads-Konto nicht in dieser Zeitzone befindet, sollten Sie diese Methoden daher im Allgemeinen vermeiden.

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, wenn Sie das Jahr, den Monat, das Datum, den Tag, die Stunden oder die Minuten für ein Datumsobjekt in der Zeitzone Ihres Kontos abrufen möchten.

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, 2025 13:00:00 -0500');

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

Beispiel: So erstellen Sie ein Datumsobjekt für heute Mittag 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 nicht das Muster „z“, um Datumsstrings zu erstellen, die an einen Datumskonstruktor übergeben werden, da der Konstruktor sie nicht immer parsen kann. Verwenden Sie nur das Muster „Z“.

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 getTime() für Datumsberechnungen. Wenn Sie getTime() für ein Datumsobjekt aufrufen, wird die Anzahl der Millisekunden seit dem 1. Januar 1970 (UTC) zurückgegeben. Sie können Berechnungen für diesen Wert ausführen und den neuen Wert dann mit setTime() auf ein Datumsobjekt anwenden oder 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 zurück.

Berichte

Wenn Sie einen Bericht mit AdsApp.search() abrufen, müssen die Datumsangaben in der GAQL-Abfrage im Format yyyy-MM-dd angegeben werden (z. B. 2025-06-30 für den 30. Juni 2025).

Ebenso müssen die Datumsangaben für die Methode getStatsFor() angegeben werden, die für viele Google Ads-Skriptobjekte verfügbar ist. 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, wird die Zeitzone der Tabelle verwendet, um dieses Datum zu interpretieren. Angenommen, wir haben eine Tabelle, deren Zeitzone auf „Pazifische Zeit“ festgelegt ist:

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

Der Wert in A1 ist „17-Feb-25 10:00:00“.

Damit Datumsobjekte wie erwartet in eine Tabelle geschrieben werden, legen Sie die Zeitzone der Tabelle so fest, dass sie mit der Zeitzone Ihres Google Ads-Kontos übereinstimmt:

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

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