Aby omawiać nasze usługi i przekazywać opinie na ich temat, dołącz do oficjalnego kanału Google Ads na Discordzie na serwerze społeczności Google Advertising and Measurement.

Ta strona została przetłumaczona przez Cloud Translation API.

Praca z datami i godzinami

Skrypty Google Ads często muszą przetwarzać daty i godziny. Typowe przypadki użycia to m.in. pobieranie raportów za określony zakres dat, planowanie uruchamiania kampanii lub grup reklam o określonych porach oraz eksportowanie do arkusza kalkulacyjnego czasu ostatniego uruchomienia skryptu. Ten przewodnik opisuje ważne pojęcia, typowe pułapki i zalecane podejścia podczas pracy z datami i godzinami w skryptach Google Ads.

Podstawowe pojęcia

Aby pracować z datami i godzinami w skryptach Google Ads, używaj wbudowanego w JavaScript obiektu daty. Obiekt daty JavaScriptu reprezentuje konkretny 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, 2025 13:00:00 -0500');

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

Nowi użytkownicy Skryptów często nie wiedzą, jak obiekty daty obsługują strefy czasowe. Naturalnym, ale nieprawidłowym sposobem myślenia o obiekcie daty jest traktowanie go jako czasu na zegarze w jednej strefie czasowej. Na przykład w powyższym fragmencie kodu niektórzy użytkownicy błędnie zakładają, że date jest prawidłowy tylko w jednej strefie czasowej, a mianowicie w strefie czasowej z 5-godzinnym przesunięciem, która została użyta do jego utworzenia. W tym błędnym widoku date należałoby „przekonwertować”, aby można było go używać w innych strefach czasowych.

Prawidłowe podejście do obiektu daty polega na traktowaniu go jako konkretnego momentu w czasie niezależnego od strefy czasowej. Chociaż w różnych strefach czasowych ten sam moment jest pokazywany na zegarach w inny sposób, jest to ten sam moment. Weźmy na przykład ten fragment kodu:

// Create two date objects with different times and timezone 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);

Obiekt daty reprezentuje konkretny moment w czasie, więc nie trzeba go „konwertować” w różnych strefach czasowych. Zamiast tego może być renderowana jako ciąg znaków sformatowany dla określonej strefy czasowej.

Aby wyrenderować datę jako ciąg znaków w określonym formacie i strefie czasowej, użyj funkcji Utilities.formatDate(date, timeZone, format). Przykład: 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\''));

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 jest uruchamiany skrypt, użyj AdsApp.currentAccount().getTimeZone().

Typowe problemy

Oto kilka typowych problemów, które mogą wystąpić w przypadku dat.

Domyślna strefa czasowa podczas rejestrowania obiektu daty

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

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

// Mon Feb 17 10:00:00 GMT-08:00 2025
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 daty jako ciąg znaków przy użyciu niestandardowego formatu i strefy czasowej na potrzeby logowania lub inne, zawsze używaj 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 zawiera przesunięcia strefy czasowej, strefa czasowa jest przyjmowana jako 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, 2025 13:00:00');

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

Podczas tworzenia obiektu daty za pomocą ciągu znaków zawsze uwzględniaj przesunięcie strefy czasowej, aby mieć pewność, że obiekt daty reprezentuje moment w czasie, który Cię interesuje.

Domyślna strefa czasowa w metodach obiektu daty

Obiekty daty w JavaScript mają kilka metod, które przyjmują domyślną strefę czasową, np.:

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

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

W skryptach Google Ads domyślną strefą czasową jest America/Los_Angeles (czas pacyficzny), niezależnie od strefy czasowej powiązanej z kontem Google Ads. Dlatego, jeśli Twoje konto Google Ads nie jest w tej strefie czasowej, unikaj korzystania z tych metod.

Aby uzyskać rok, miesiąc, datę, dzień, godzinę lub minuty z obiektu daty w strefie czasowej konta, użyj funkcji Utilities.formatDate(date, timeZone, format) z formatem określającym część daty lub czasu, którą chcesz uzyskać, oraz funkcji AdsApp.currentAccount().getTimeZone(), aby uzyskać strefę czasową konta.

Tworzenie obiektu daty na podstawie sformatowanego ciągu daty

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

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

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

Aby na przykład utworzyć obiekt daty dla południa bieżącego dnia w strefie czasowej bieżącego konta:

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” do tworzenia ciągów dat, które będą przekazywane do konstruktora daty, ponieważ konstruktor nie zawsze będzie w stanie je przeanalizować. Używaj tylko wzoru „Z”.

Obliczenia na datach

Niektóre skrypty muszą wykonywać proste obliczenia na datach, np. znajdować datę X dni przed lub po danej dacie. Podczas wykonywania obliczeń na datach używaj znaku getTime(). Wywołanie metody getTime() na obiekcie daty zwraca liczbę milisekund od początku 1 stycznia 1970 r. czasu UTC. Możesz wykonać na tej wartości działania matematyczne, a następnie 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ą metody AdsApp.search() zapytanie GAQL wymaga podania dat w formacie yyyy-MM-dd (np. 2025-06-30 to 30 czerwca 2025 r.).

Podobnie metoda getStatsFor() dostępna w wielu obiektach skryptów Google Ads wymaga podania dat w tym samym formacie. Użyj funkcji Utilities.formatDate(date, timeZone, format) do sformatowania obiektu daty w tym formacie.

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

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żywana jest strefa czasowa arkusza kalkulacyjnego. Załóżmy na przykład, że mamy arkusz kalkulacyjny, w którym strefa czasowa jest ustawiona na czas pacyficzny:

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

W komórce A1 pojawi się wartość 17-Feb-25 10:00:00.

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

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

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