Menggunakan Tanggal dan Waktu

Skrip Google Ads sering kali perlu menggunakan 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 adalah 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. J cara alami tetapi salah untuk membayangkan objek tanggal adalah sebagai 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 pandangan yang salah tersebut, date harus "dikonversi" agar dapat digunakan di zona waktu lain.

Namun, cara yang benar untuk memikirkan objek tanggal adalah sebagai momen dalam waktu apa pun tidak bergantung pada zona waktu apa pun. Meskipun momen tertentu ditampilkan secara berbeda pada jam di zona waktu yang berbeda, momen tersebut sama. Sebagai 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 dalam waktu tertentu, objek tersebut tidak perlu menjadi "dikonversi" melintasi zona waktu. Sebaliknya, 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 zona waktu ID. 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 ke dalam log

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/Los_Angeles (waktu Pasifik), terlepas dari zona waktu yang terkait dengan akun Google Ads. Jika Anda ingin merender objek tanggal sebagai {i>string<i} menggunakan format khusus dan zona waktu untuk pencatatan log 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 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()

Hal ini juga mencakup set___() yang setara dengan 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 jika akun Google Ads Anda berada di zona waktu ini, Anda umumnya harus 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 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 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'.

Penghitungan tanggal

Beberapa skrip perlu melakukan perhitungan 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 bisa melakukan perhitungan pada nilai ini, lalu terapkan nilai baru ke objek tanggal menggunakan setTime() atau berikan sebagai 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 mengharuskan tanggal ditentukan dalam format yyyy-MM-dd (misalnya, 2021-06-30 adalah 30 Juni 2021).

Demikian juga, metode getStatsFor() yang tersedia di banyak skrip Google Ads objek membutuhkan 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 {i>spreadsheet<i} dengan meneruskan objek tanggal, zona waktu {i>spreadsheet<i} 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.