Menggunakan Tanggal dan Waktu

Skrip Google Ads sering kali harus berfungsi dengan tanggal dan waktu. Kasus penggunaan yang umum mencakup mengambil laporan untuk rentang tanggal tertentu, menjadwalkan kampanye atau grup iklan untuk dijalankan pada waktu tertentu, dan membuat output ke spreadsheet saat skrip terakhir berjalan. 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 dalam waktu 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 wajar tetapi salah untuk menganggap objek tanggal adalah waktu pada jam dalam satu zona waktu. Misalnya, dalam cuplikan di atas, beberapa pengguna salah berasumsi 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 harus "dikonversi" untuk digunakan di zona waktu lain.

Sebaliknya, cara yang 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 sama. Misalnya, pertimbangkan 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 mewakili objek tanggal sebagai jumlah milidetik sejak 1 Januari 1970 UTC.

Karena objek tanggal mewakili momen dalam waktu tertentu, objek tersebut tidak perlu "dikonversi" di seluruh zona waktu. Sebaliknya, item tersebut 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 ke dalam log 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/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 tersebut diasumsikan sebagai Amerika/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 waktu yang benar-benar 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___() metode ini (misalnya, setMonth()), dan getTimezoneOffset().

Dalam skrip Google Ads, zona waktu default adalah Amerika/Los_Angeles (waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Oleh karena itu, kecuali jika akun Google Ads Anda berada dalam zona waktu ini, umumnya Anda sebaiknya menghindari penggunaan 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 berformat 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 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'.

Penghitungan tanggal

Beberapa skrip perlu melakukan penghitungan sederhana dengan tanggal, seperti menemukan tanggal X hari sebelum atau setelah 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 menghitung 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 mengharuskan tanggal ditentukan dalam format yang sama. Gunakan Utilities.formatDate(date, timeZone, format) untuk memformat objek tanggal dalam format ini.

Misalnya, untuk mengambil laporan satu sampai 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. Contohnya, anggaplah kita memiliki {i>spreadsheet<i} 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 dalam A1 adalah 17-Feb-21 10:00:00.

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

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

Anda juga dapat menyetel waktu spreadsheet secara manual.