Menggunakan Tanggal dan Waktu

Skrip Google Ads sering kali perlu menyertakan tanggal dan waktu. Kasus penggunaan umum meliputi pengambilan laporan untuk rentang tanggal tertentu, menjadwalkan kampanye atau grup iklan untuk dijalankan pada waktu tertentu, dan menampilkan waktu terakhir skrip dijalankan ke spreadsheet. Panduan ini menjelaskan konsep penting, kesalahan umum, dan pendekatan yang direkomendasikan saat menggunakan 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. 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, 2021 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 memahami objek tanggal adalah sebagai waktu pada jam dalam satu zona waktu. Misalnya, dalam cuplikan di atas, beberapa pengguna salah mengira bahwa date hanya valid di satu zona waktu, yaitu zona waktu dengan offset -5 jam yang digunakan untuk membuatnya. Dalam tampilan yang salah tersebut, date harus "dikonversi" agar dapat digunakan di zona waktu lain.

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

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

Catatan: Secara internal, JavaScript merepresentasikan objek tanggal sebagai jumlah milidetik sejak 1 Januari 1970 UTC.

Karena objek tanggal mewakili momen tertentu, objek tersebut tidak perlu "dikonversi" di seluruh zona waktu. Namun, 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). Contoh:

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

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

Zona waktu default saat mencatat objek tanggal

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

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

// Wed Feb 17 10:00:00 GMT-08:00 2021
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 kustom dan zona waktu untuk logging atau tujuan lainnya, 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 dianggap 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, 2021 13:00:00');

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

Saat membuat objek tanggal menggunakan string, selalu sertakan offset zona waktu untuk memastikan objek tanggal mewakili momen 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()

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

Dalam skrip Google Ads, zona waktu default adalah Amerika Serikat/Los_Angeles (waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Oleh karena itu, kecuali akun Google Ads Anda berada dalam zona waktu ini, sebaiknya hindari penggunaan metode tersebut.

Guna 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, 2021 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 pada siang hari 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 mengurainya. Hanya gunakan pola 'Z'.

Matematika tanggal

Beberapa skrip perlu melakukan penghitungan sederhana dengan tanggal, seperti menemukan tanggal X hari sebelum atau setelah tanggal tertentu. Saat melakukan matematika 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 tepat 24 jam yang lalu.

Pelaporan

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

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 menetapkan 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, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

Nilai di A1 akan menjadi 17-Feb-21 10:00:00.

Untuk memastikan objek tanggal ditulis ke spreadsheet seperti 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.