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

Praca z datami i godzinami
Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Scenariusze Google Ads często muszą pracować z datami i czasami. Typowe przypadki użycia obejmują pobieranie raportów dotyczących 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. Ten przewodnik zawiera opis ważnych pojęć, typowych błędów i zalecanych metod pracy z datami i czasem w skryptach Google Ads.

Podstawowe pojęcia

Aby pracować z datami i czasami w skryptach Google Ads, użyj wbudowanego obiektu daty w JavaScript. 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. 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 ujęciu date musiałby zostać „przekształcony”, aby można go było używać w innych strefach czasowych.

Zamiast tego właściwym sposobem myślenia o obiekcie data jest traktowanie go jako konkretnego momentu w czasie niezależnego 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, 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 data reprezentuje konkretny moment w czasie, więc nie trzeba go „konwertować” w różnych strefach czasowych. Zamiast tego może być renderowany 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, 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 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, 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 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ślny czas strefy podczas tworzenia obiektu daty,

Podczas tworzenia obiektu daty za pomocą ciągu, który nie zawiera przesunięcia strefy czasowej, za taką strefę przyjmuje się 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 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 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 czasu, 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 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 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. Podczas wykonywania obliczeń dotyczących daty używaj funkcji getTime(). Wywołanie metody getTime() na obiekcie date zwraca liczbę milisekund od początku 1 stycznia 1970 r. czasu 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ą zapytania AdsApp.search() zapytanie GAQL wymaga, aby daty były podawane 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 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 czasowej arkusza kalkulacyjnego. Załóżmy na przykład, że mamy arkusz kalkulacyjny, w którym ustawiona jest strefa czasowa Pacyfiku:

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

Wartość w komórce A1 będzie wynosić 25-02-17 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.