To discuss and provide feedback on our products, join the official Google Ads Discord channel in the Google Advertising and Measurement Community server.

Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan Tanggal dan Waktu

Skrip Google Ads sering kali perlu menangani tanggal dan waktu. Kasus penggunaan umum mencakup pengambilan laporan untuk rentang tanggal tertentu, menjadwalkan kampanye atau grup iklan untuk dijalankan pada waktu tertentu, dan menampilkan waktu terakhir kali skrip dijalankan ke spreadsheet. Panduan ini menjelaskan konsep penting, kesalahan umum, dan pendekatan yang direkomendasikan saat bekerja dengan tanggal dan waktu dalam skrip Google Ads.

Konsep dasar

Untuk menggunakan tanggal dan waktu dalam skrip Google Ads, gunakan objek tanggal bawaan JavaScript. Objek tanggal JavaScript mewakili momen tertentu dalam waktu. Ada beberapa cara untuk membuat objek tanggal baru:

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

Pengguna Skrip baru sering kali bingung dengan cara objek tanggal menangani zona waktu. Cara yang alami, tetapi salah untuk memikirkan objek tanggal adalah sebagai waktu pada jam dalam satu zona waktu. Misalnya, dalam cuplikan di atas, beberapa pengguna keliru menganggap bahwa date hanya valid dalam satu zona waktu, yaitu zona waktu dengan selisih -5 jam yang digunakan untuk membuatnya. Dalam tampilan yang salah tersebut, date perlu "dikonversi" agar dapat digunakan di zona waktu lain.

Sebaliknya, cara benar untuk memikirkan objek tanggal adalah sebagai momen tertentu dalam waktu yang tidak bergantung pada zona waktu mana pun. Meskipun momen tertentu ditampilkan secara berbeda pada jam di zona waktu yang berbeda, momen tersebut tetap sama. Misalnya, perhatikan cuplikan ini:

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

Karena objek tanggal merepresentasikan momen tertentu dalam waktu, objek tersebut tidak perlu "dikonversi" di seluruh zona waktu. Sebagai gantinya, tanggal dapat dirender sebagai string yang diformat untuk zona waktu tertentu.

Untuk merender tanggal sebagai string dengan format dan zona waktu tertentu, gunakan Utilities.formatDate(date, timeZone, format). Misalnya: 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\''));

Contoh ini menentukan zona waktu secara langsung menggunakan ID zona waktu. Untuk mengambil zona waktu yang terkait dengan akun Google Ads yang menjalankan skrip Anda, gunakan AdsApp.currentAccount().getTimeZone().

Kesalahan umum

Berikut beberapa kesalahan umum yang terjadi pada tanggal.

Zona waktu default saat mencatat objek tanggal

Saat mencatat objek tanggal secara langsung menggunakan Logger.log(), objek tersebut dirender menggunakan format dan zona waktu default. Contoh:

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

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

Zona waktu default adalah Amerika Serikat/Los_Angeles (waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Jika Anda ingin merender objek tanggal sebagai string menggunakan format dan zona waktu kustom untuk logging atau tujuan lain, selalu gunakan Utilities.formatDate(date, timeZone, format).

Zona waktu default saat membuat objek tanggal

Saat membuat objek tanggal menggunakan string yang tidak memberikan offset zona waktu, zona waktu diasumsikan sebagai America/Los_Angeles (Waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Contoh:

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

Saat membuat objek tanggal menggunakan string, selalu sertakan selisih zona waktu untuk memastikan objek tanggal merepresentasikan momen waktu yang sebenarnya Anda inginkan.

Zona waktu default dalam metode objek tanggal

Objek tanggal JavaScript memiliki beberapa metode yang mengasumsikan zona waktu default, seperti:

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

Hal ini juga mencakup padanan set___() dari metode ini (misalnya, setMonth()), dan getTimezoneOffset().

Dalam skrip Google Ads, zona waktu default adalah America/Los_Angeles (waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Oleh karena itu, kecuali akun Google Ads Anda berada di zona waktu ini, sebaiknya Anda tidak menggunakan metode ini.

Untuk mendapatkan tahun, bulan, tanggal, hari, jam, atau menit untuk objek tanggal di zona waktu akun Anda, gunakan Utilities.formatDate(date, timeZone, format) dengan format yang menentukan bagian tanggal atau waktu yang Anda inginkan, dan gunakan AdsApp.currentAccount().getTimeZone() untuk mendapatkan zona waktu akun Anda.

Membuat objek tanggal dari string tanggal yang diformat

Anda dapat membuat objek tanggal dengan meneruskan string tanggal yang diformat ke konstruktor tanggal. Contoh:

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

Konstruktor hanya dapat mengurai format string tanggal tertentu. Untuk memastikan string tanggal Anda diuraikan dengan benar, selalu berikan dalam format MMMM dd, yyyy HH:mm:ss Z.

Misalnya, untuk membuat objek tanggal untuk siang ini di zona waktu akun saat ini:

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

Jangan gunakan pola 'z' untuk membuat string tanggal yang akan diteruskan ke konstruktor tanggal, karena konstruktor tidak akan selalu dapat menguraikannya. Hanya gunakan pola 'Z'.

Matematika tanggal

Beberapa skrip perlu melakukan perhitungan matematika sederhana dengan tanggal, seperti menemukan tanggal X hari sebelum atau sesudah tanggal tertentu. Saat melakukan penghitungan tanggal, gunakan getTime(). Memanggil getTime() pada objek tanggal akan menampilkan jumlah milidetik sejak awal 1 Januari 1970 UTC. Anda dapat melakukan perhitungan matematika pada nilai ini, lalu menerapkan nilai baru ke objek tanggal menggunakan setTime() atau memberikannya sebagai parameter saat membuat objek tanggal baru.

Contoh:

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

Dalam contoh ini, yesterday adalah tepat 24 jam yang lalu.

Pelaporan

Saat mengambil laporan menggunakan AdsApp.search(), kueri GAQL memerlukan tanggal yang ditentukan dalam format yyyy-MM-dd (misalnya, 2025-06-30 adalah 30 Juni 2025).

Demikian pula, metode getStatsFor() yang tersedia di banyak objek skrip Google Ads memerlukan tanggal yang ditentukan dalam format yang sama. Gunakan Utilities.formatDate(date, timeZone, format) untuk memformat objek tanggal dalam format ini.

Misalnya, untuk mengambil laporan dari satu hingga tiga hari yang lalu:

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

Spreadsheet

Skrip Google Ads sering kali menulis output ke spreadsheet, termasuk objek tanggal. Saat menyetel sel dalam spreadsheet dengan meneruskan objek tanggal, zona waktu spreadsheet digunakan untuk menafsirkan tanggal tersebut. Misalnya, kita memiliki spreadsheet yang zona waktunya disetel ke Waktu Pasifik:

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

Nilai di A1 adalah 17-Feb-25 10.00.00.

Untuk memastikan objek tanggal ditulis ke spreadsheet sesuai yang Anda harapkan, tetapkan zona waktu spreadsheet agar cocok dengan zona waktu akun Google Ads Anda:

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

Anda juga dapat menyetel waktu spreadsheet secara manual.