Praca z datami i godzinami

Scenariusze Google Ads często muszą pracować z datami i czasami. Typowe przypadki użycia obejmują pobieranie raportów z określonego zakresu dat, planowanie kampanii lub grup reklam do wyświetlania w określonych godzinach oraz zapisywanie w arkuszu kalkulacyjnym czasu ostatniego uruchomienia skryptu. W tym przewodniku opisujemy ważne pojęcia, częste błędy i zalecane podejścia do pracy z datami i czasem w skryptach Google Ads.

Podstawowe pojęcia

Aby edytować daty i godziny w skryptach Google Ads, użyj wbudowanego obiektu daty w JavaScripcie. Obiekt daty JavaScript reprezentuje określony moment w czasie. Nowy obiekt daty można utworzyć na kilka sposobów:

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

Użytkownicy nowych skryptów często są zdezorientowani tym, jak obiekty daty obsługują strefy czasowe. Naturalny, ale nieprawidłowy sposób postrzegania obiektu Date jest jako czas na zegarku w jednej strefie czasowej. Na przykład w przypadku kodu źródłowego powyżej niektórzy użytkownicy błędnie zakładają, że date jest prawidłowy tylko w jednej strefie czasowej, a mianowicie w strefie czasowej z odchyleniem -5 godzin, która została użyta do jego utworzenia. W takim błędnym widoku element date musiałby zostać „przekonwertowany”, aby można go było używać w innych strefach czasowych.

Zamiast tego prawidłowy sposób myślenia o obiekcie data to konkretny moment w czasie niezależny od strefy czasowej. Chociaż dany moment jest wyświetlany w różny sposób na zegarach w różnych strefach czasowych, jest to ten sam moment. Weźmy na przykład ten fragment:

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

Obiekt data reprezentuje konkretny moment w czasie, więc nie trzeba go „konwertować” w różnych strefach czasowych. Zamiast tego może być wyświetlany jako ciąg znaków sformatowany pod kątem konkretnej strefy czasowej.

Aby wyświetlić datę jako ciąg znaków w określonym formacie i strefie czasowej, użyj znaku Utilities.formatDate(date, timeZone, format). Na przykład:

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

W tych przykładach strefa czasowa została określona bezpośrednio za pomocą identyfikatora strefy czasowej. Aby pobrać strefę czasową powiązaną z kontem Google Ads, na którym działa skrypt, użyj parametru AdsApp.currentAccount().getTimeZone().

Typowe pułapki

Domyślna strefa czasowa podczas rejestrowania obiektu daty

Gdy obiekt daty jest rejestrowany bezpośrednio za pomocą funkcji Logger.log(), jest renderowany przy użyciu domyślnego formatu i strefy czasowej. Na przykład:

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

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

Domyślna strefa czasowa to America/Los_Angeles (czas pacyficzny), niezależnie od strefy czasowej powiązanej z kontem Google Ads. Jeśli chcesz renderować obiekt date jako ciąg znaków z użyciem niestandardowego formatu i strefy czasowej do logowania lub innych celów, zawsze używaj Utilities.formatDate(date, timeZone, format).

domyślny czas strefy podczas tworzenia obiektu daty,

Gdy tworzysz obiekt daty za pomocą ciągu znaków, który nie podaje przesunięcia strefy czasowej, przyjmuje się, że strefa czasowa to America/Los_Angeles (czas pacyficzny) niezależnie od strefy czasowej powiązanej z kontem Google Ads. Przykład:

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

Podczas tworzenia obiektu daty za pomocą ciągu zawsze uwzględniaj przesunięcie strefy czasowej, aby mieć pewność, że obiekt daty reprezentuje właściwy moment.

Domyślna strefa czasowa w metodach obiektu Date

Obiekty daty JavaScript mają kilka metod, które zakładają domyślny czas strefy czasowej, takich jak:

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

Obejmuje to również ich odpowiedniki set___() (np. setMonth()) i getTimezoneOffset().

W skryptach Google Ads domyślna strefa czasowa to America/Los_Angeles (czas pacyficzny), niezależnie od strefy czasowej powiązanej z kontem Google Ads. Dlatego, jeśli Twoje konto Google Ads nie znajduje się w tym samym czasie lokalnym, zazwyczaj nie używaj tych metod.

Aby uzyskać rok, miesiąc, dzień, godzinę lub minutę obiektu daty w strefie czasowej konta, użyj funkcji Utilities.formatDate(date, timeZone, format) w formacie określającym odpowiednią część daty lub godziny, a następnie użyj funkcji AdsApp.currentAccount().getTimeZone(), aby uzyskać strefę czasową konta.

Tworzenie obiektu daty na podstawie sformatowanego ciągu znaków daty

Obiekt daty możesz utworzyć, przekazując do konstruktora daty sformatowany ciąg znaków z datą. Na przykład:

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

Konstruktor może analizować tylko określone formaty ciągów znaków daty. Aby mieć pewność, że ciąg znaków daty zostanie poprawnie przeanalizowany, zawsze podawaj go w formacie MMMM dd, yyyy HH:mm:ss Z.

Aby na przykład utworzyć obiekt daty odpowiadający godzinie 12:00 w bieżącej strefie czasowej na koncie:

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

Nie używaj wzorca „z”, aby tworzyć ciągi znaków daty, które będą przekazywane do konstruktora daty, ponieważ konstruktor nie zawsze będzie mógł go przeanalizować. Używaj tylko wzorca „Z”.

Obliczanie dat

Niektóre skrypty wymagają wykonywania prostych obliczeń dotyczących dat, np. znajdowania daty X dni przed lub po danej dacie. Do obliczeń matematycznych używaj funkcji getTime(). Wywołanie metody getTime() na obiekcie date zwraca liczbę milisekund od 1 stycznia 1970 r. czasu UTC. Możesz wykonać obliczenia na tej wartości, a potem zastosować ją do obiektu daty za pomocą funkcji setTime() lub podać ją jako parametr podczas tworzenia nowego obiektu daty.

Na przykład:

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

W tym przykładzie yesterday to dokładnie 24 godziny temu.

Raportowanie

Podczas pobierania raportu za pomocą narzędzia AdsApp.search() zapytanie GAQL wymaga podania dat w formacie yyyy-MM-dd (np. 2021-06-30 oznacza 30 czerwca 2021 r.).

Podobnie metoda getStatsFor(), dostępna w wielu obiektach skryptów Google Ads, wymaga podawania dat w tym samym formacie. Aby sformatować obiekt daty w tym formacie, użyj elementu Utilities.formatDate(date, timeZone, format).

Aby na przykład pobrać raport z okresu od 1 do 3 dni:

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

Arkusze kalkulacyjne

Skrypty Google Ads często zapisują dane wyjściowe w arkuszu kalkulacyjnym, w tym obiekty daty. Podczas ustawiania komórki w arkuszu kalkulacyjnym przez przekazanie obiektu daty, do interpretacji tej daty używany jest czas strefy arkusza kalkulacyjnego. Załóżmy np., że mamy arkusz kalkulacyjny z strefą czasową ustawioną na czas pacyficzny:

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

Wartość w komórce A1 będzie wynosić 17-Feb-21 10:00:00.

Aby mieć pewność, że obiekty daty są zapisywane w arkuszu kalkulacyjnym zgodnie z oczekiwaniami, ustaw strefę czasową arkusza kalkulacyjnego tak, aby odpowiadała strefie czasowej Twojego konta Google Ads:

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

Możesz też ustawić czas arkusza kalkulacyjnego ręcznie.