Datums- und Uhrzeitangaben verwenden

In Verbindung mit AdWords-Skripts werden oft Datums- und Uhrzeitangaben verwendet. Häufige Anwendungsfälle hierfür sind etwa das Abrufen von Berichten für einen bestimmten Zeitraum, das Planen der Schaltung von Kampagnen oder Anzeigengruppen zu bestimmten Zeiten und die Ausgabe der Uhrzeit der letzten Skriptausführung in eine Tabelle. In diesem Leitfaden werden grundlegende Konzepte, häufige Fehler und empfohlene Vorgehensweisen für die Verwendung von Datums- und Uhrzeitangaben in AdWords-Skripts beschrieben.

Grundlegende Konzepte

Um Datums- und Uhrzeitangaben in AdWords-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.
var now = new Date();

// Create a date object for a past date and time using a formatted string.
var date = new Date('February 17, 2016 13:00:00 -0500');

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

Neuen Skriptnutzern ist oft nicht ganz klar, wie Zeitzonen von Datumsobjekten behandelt werden. Datumsobjekte stehen nicht für die Zeit, die in einer Zeitzone auf einer Uhr angezeigt wird. Im obigen Snippet gehen einige Nutzer irrtümlicherweise davon aus, dass date nur in einer Zeitzone gültig ist – in der Zone mit einer Zeitverschiebung von -5 Stunden, die für die Erstellung verwendet wurde. Wenn das der Fall wäre, müsste date konvertiert werden, damit eine Verwendung in anderen Zeitzonen möglich wäre.

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. Nehmen wir einmal dieses Snippet als Beispiel:

// Create two date objects with different times and timezone offsets.
var date1 = new Date('February 17, 2016 13:00:00 -0500');
var date2 = new Date('February 17, 2016 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.
Logger.log(date1.getTime() == date2.getTime());

// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
Logger.log(date1 == date2);

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), damit ein Datum als String mit einem bestimmten Format und mit einer bestimmten Zeitzone dargestellt wird. Beispiel:

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

// February 17, 2016 13:00:00 -0500
Logger.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2016 10:00:00 -0800
Logger.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2016-02-17T18:00:00.000Z
Logger.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. Um die Zeitzone abzurufen, die dem AdWords-Konto zugeordnet ist, über das Ihr Skript ausgeführt wird, verwenden Sie AdWordsApp.currentAccount().getTimeZone().

Häufige Fehler

Standardzeitzone bei der Erfassung eines Datumsobjekts

Wenn ein Datumsobjekt direkt mit Logger.log() erfasst wird, werden ein Standardformat und eine Standardzeitzone für die Darstellung verwendet. Beispiel:

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

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

Die Standardzeitzone ist PST (Los Angeles) – unabhängig davon, welche Zeitzone für das AdWords-Konto festgelegt ist. Wenn das Datumsobjekt zu Erfassungs- oder anderen Zwecken als String mit einem benutzerdefinierten Format und einer benutzerdefinierten Zeitzone dargestellt 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 AdWords-Konto festgelegt ist. Beispiel:

// Create a date without specifying the timezone offset.
var date = new Date('February 17, 2016 13:00:00');

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

Wenn Sie ein Datumsobjekt mithilfe eines Strings erstellen, geben Sie immer die Zeitverschiebung an. So ist sichergestellt, dass das Datumsobjekt stets dem gewünschten Zeitpunkt entspricht.

Standardzeitzone in Datumsobjektmethoden

Bei mehreren Methoden von JavaScript-Datumsobjekten wird von einer Standardzeitzone ausgegangen. Hierzu zählen etwa getFullYear(), getMonth(), getDate(), getDay(), getHours() und getMinutes() sowie deren set___()-Entsprechungen und getTimezoneOffet(). In AdWords-Skripts ist die Standardzeitzone PST (Los Angeles) – unabhängig davon, welche Zeitzone für das AdWords-Konto festgelegt ist. Daher sollten Sie diese Methoden generell nur verwenden, wenn sich Ihr AdWords-Konto in dieser Zeitzone befindet.

Sollte für Ihr Konto hingegen eine andere Zeitzone festgelegt sein, verwenden Sie stets Utilities.formatDate(date, timeZone, format), um Jahre, Tage, Stunden und Minuten von Datumsobjekten abzurufen. Geben Sie dabei über das jeweilige Format an, welchen Teil des Datums oder der Uhrzeit Sie abrufen möchten. Um die Zeitzone Ihres Kontos abzurufen, verwenden Sie AdWordsApp.currentAccount().getTimeZone().

Datumsobjekt auf der Grundlage eines formatierten Datumsstrings erstellen

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

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

Der Konstruktor kann nur bestimmte Datumsstringformate parsen. Verwenden Sie für den Datumsstring stets das Format MMMM TT, JJJJ HH:MM:SS Z, um sicherzustellen, dass er korrekt geparst wird.

Beispielcode für ein Datumsobjekt für 12:00 Uhr am aktuellen Tag in der Zeitzone des derzeitigen Kontos:

var now = new Date();
var timeZone = AdWordsApp.currentAccount().getTimeZone();
var noonString = Utilities.formatDate(now, timeZone,
                                      'MMMM dd, yyyy 12:00:00 Z')
var noon = new Date(noonString);

Verwenden Sie das "z"-Muster nicht, um Datumsstrings zu erstellen, die an einen Datumskonstruktor übergeben werden, da dieses nicht immer vom Konstruktor geparst werden kann. Verwenden Sie ausschließlich 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 stets getTime(). Wenn Sie für ein Datumsobjekt getTime() aufrufen, wird die Anzahl der Millisekunden seit dem 1. Januar 1970 (UTC) zurückgegeben. Sie können Berechnungen auf Basis dieses Werts anstellen und den neuen Wert dann mithilfe von setTime() auf ein Datumsobjekt anwenden. Alternativ haben Sie die Möglichkeit, den ermittelten Wert beim Erstellen eines neuen Datumsobjekts als Parameter zu verwenden.

Beispiel:

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

In diesem Beispiel liegt yesterday vor genau 24 Stunden.

Berichte

Wenn ein Bericht mit AdWordsApp.report(query, optArgs) abgerufen wird, müssen die Datumsangaben für die AWQL-Abfrage als achtstellige Integer (JJJJMMTT) vorliegen. Datumsangaben in Form von achtstelligen Integern sind auch für die Methode getStatsFor() erforderlich, die für viele AdWords-Skriptobjekte verfügbar ist. Verwenden Sie Utilities.formatDate(date, timeZone, format), um ein Datumsobjekt entsprechend zu formatieren.

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

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
var to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);

var timeZone = AdWordsApp.currentAccount().getTimeZone();
var report = AdWordsApp.report(
  'SELECT CampaignName, Clicks ' +
  'FROM   CAMPAIGN_PERFORMANCE_REPORT ' +
  'DURING ' + Utilities.formatDate(from, timeZone, 'yyyyMMdd') + ','
            + Utilities.formatDate(to, timeZone, 'yyyyMMdd'));

Tabellen

Bei AdWords-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. Hier ein Beispiel für eine Tabelle mit der Zeitzone PST:

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

Zelle A1 enthält in diesem Fall den Wert "17-Feb-16 10:00:00".

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

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

Sie haben auch die Möglichkeit, die Zeitzone einer Tabelle manuell zu ändern.

Feedback geben zu...

AdWords Scripts
AdWords Scripts