Praca z datami i godzinami

Skrypty Google Ads często muszą współpracować z datami i godzinami. 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, typowe pułapki, i zalecane metody pracy z datami i godzinami w Google Ads skryptów.

Podstawowe pojęcia

Aby w scenariuszach Google Ads pracować z datami i czasem, użyj wbudowanego obiektu daty w JavaScript. Obiekt daty JavaScript reprezentuje określony moment w czasie. Istnieje kilka sposobów tworzenia nowych obiektów daty:

// 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 to godzina 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 tym błędnym ujęciu date musiałby zostać „przekształcony”, aby można go było używać w innych strefach czasowych.

Według właściwego sposobu myślenia o obiekcie daty jest w czasie niezależnie 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ź pod uwagę ten fragment kodu:

// 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ć strefa czasowa powiązana z kontem Google Ads, na którym działa Twój skrypt, użyj 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ślną strefą czasową jest America/Los_Angeles (czas pacyficzny), niezależnie od w strefie czasowej powiązanej z kontem Google Ads. Jeśli chcesz wyświetlić obiekt daty jako ciąg znaków przy użyciu niestandardowego formatu i strefy czasowej na potrzeby rejestrowania lub w innych celach, zawsze używaj funkcji Utilities.formatDate(date, timeZone, format).

Domyślna strefa czasowa podczas tworzenia obiektu daty

podczas tworzenia obiektu daty za pomocą ciągu znaków, który nie określa 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);

Tworząc obiekt daty z ciągiem znaków, zawsze uwzględnij przesunięcie strefy czasowej na Upewnij się, że obiekt daty odpowiada żądanemu momentowi.

Domyślna strefa czasowa w metodach obiektów daty

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 zalecamy korzystania z 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 niej sformatowany ciąg znaków z datą za pomocą konstruktora. 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 z datą. Aby upewnić się, że atrybuty ciąg daty jest 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”.

Matematyka daty

Niektóre skrypty muszą wykonać proste obliczenia matematyczne z datami, np. znaleźć datę X. dni przed określoną datą lub po niej. Do obliczeń matematycznych używaj funkcji getTime(). Wywołanie getTime() w obiekcie daty zwraca liczbę milisekund od od 1 stycznia 1970 r. UTC. Możesz wykonać na tej wartości działania matematyczne, a potem zastosować nową wartość 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ą parametru AdsApp.search() w zapytaniu GAQL należy podać daty w formacie yyyy-MM-dd (np. 2021-06-30 to 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 funkcja w arkuszu kalkulacyjnym zostanie zinterpretowana data. Załóżmy, że mamy arkusz kalkulacyjny, w którym ustawiona jest strefa czasowa Pacyfiku:

// 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 zapewnić, że obiekty są zapisywane w arkuszu kalkulacyjnym zgodnie z oczekiwaniami, ustaw parametr zgodnie ze strefą czasową na koncie Google Ads:

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

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