Tập lệnh Google Ads thường cần phải làm việc với ngày và giờ. Các trường hợp sử dụng phổ biến bao gồm truy xuất báo cáo cho một phạm vi ngày cụ thể, lên lịch chạy chiến dịch hoặc nhóm quảng cáo vào những thời điểm cụ thể và xuất thời gian chạy tập lệnh gần đây nhất vào một bảng tính. Hướng dẫn này mô tả các khái niệm quan trọng, các lỗi thường gặp và các phương pháp đề xuất khi sử dụng ngày và giờ trong tập lệnh Google Ads.
Các khái niệm cơ bản
Để xử lý ngày và giờ trong tập lệnh Google Ads, hãy sử dụng đối tượng ngày tích hợp sẵn của JavaScript. Đối tượng ngày trong JavaScript đại diện cho một thời điểm cụ thể. Có một số cách để tạo đối tượng ngày mới:
// 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);
Người dùng tập lệnh mới thường bị nhầm lẫn về cách đối tượng ngày xử lý múi giờ. Một cách tự nhiên nhưng không chính xác khi xem một đối tượng ngày là thời gian trên một đồng hồ thuộc một múi giờ duy nhất. Ví dụ: trong đoạn mã trên, một số người dùng giả định nhầm rằng date chỉ hợp lệ ở một múi giờ, cụ thể là múi giờ có độ lệch -5 giờ được dùng để tạo múi giờ đó. Trong chế độ xem nhầm lẫn đó, bạn cần phải "chuyển đổi" date để sử dụng trong các múi giờ khác.
Thay vào đó, cách chính xác để suy nghĩ về đối tượng ngày là một thời điểm cụ thể trong thời gian, độc lập với bất kỳ múi giờ nào. Mặc dù một khoảnh khắc cụ thể sẽ hiển thị khác nhau trên đồng hồ ở các múi giờ khác nhau, nhưng đó vẫn là cùng một khoảnh khắc. Ví dụ: hãy xem xét đoạn mã sau:
// 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);
Vì đối tượng ngày biểu thị một thời điểm cụ thể, nên đối tượng này không cần phải được "chuyển đổi" giữa các múi giờ. Thay vào đó, giá trị này có thể được hiển thị dưới dạng một chuỗi được định dạng cho một múi giờ cụ thể.
Để hiển thị ngày dưới dạng một chuỗi có định dạng và múi giờ cụ thể, hãy sử dụng Utilities.formatDate(date, timeZone,
format).
Ví dụ:
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\''));
Các ví dụ này chỉ định múi giờ trực tiếp bằng cách sử dụng mã nhận dạng
múi giờ. Để truy xuất múi giờ liên kết với tài khoản Google Ads đang chạy tập lệnh, hãy sử dụng AdsApp.currentAccount().getTimeZone().
Các lỗi phổ biến
Múi giờ mặc định khi ghi nhật ký đối tượng ngày
Khi trực tiếp ghi nhật ký đối tượng ngày bằng Logger.log(), đối tượng này sẽ được hiển thị bằng định dạng và múi giờ mặc định. Ví dụ:
const date = new Date('February 17, 2021 13:00:00 -0500');
// Wed Feb 17 10:00:00 GMT-08:00 2021
console.log(date);
Múi giờ mặc định là America/Los_Angeles (giờ Thái Bình Dương), bất kể múi giờ được liên kết với tài khoản Google Ads. Nếu bạn muốn hiển thị đối tượng ngày dưới dạng một chuỗi bằng cách sử dụng định dạng và múi giờ tuỳ chỉnh để ghi nhật ký hoặc cho các mục đích khác, hãy luôn sử dụng Utilities.formatDate(date, timeZone,
format).
Múi giờ mặc định khi tạo đối tượng ngày
Khi tạo một đối tượng ngày bằng một chuỗi không cung cấp độ lệch múi giờ, múi giờ được giả định là America/Los_Angeles (Giờ Thái Bình Dương), bất kể múi giờ được liên kết với tài khoản Google Ads. Ví dụ:
// 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);
Khi tạo đối tượng ngày bằng một chuỗi, hãy luôn thêm độ lệch múi giờ để đảm bảo đối tượng ngày đại diện cho thời điểm mà bạn thực sự muốn.
Múi giờ mặc định trong các phương thức đối tượng ngày
Đối tượng ngày JavaScript có một số phương thức giả định múi giờ mặc định, chẳng hạn như:
getFullYear()getMonth()getDate()getDay()getHours()getMinutes()
Điều này cũng bao gồm các phương thức tương đương set___() (ví dụ: setMonth()) và getTimezoneOffset().
Trong tập lệnh Google Ads, múi giờ mặc định là America/Los_Angeles (giờ Thái Bình Dương), bất kể múi giờ liên kết với tài khoản Google Ads đó là gì. Do đó, trừ phi tài khoản Google Ads của bạn nằm ở múi giờ này, bạn thường nên tránh sử dụng các phương thức này.
Để lấy năm, tháng, ngày, ngày, giờ hoặc phút cho một đối tượng ngày trong múi giờ của tài khoản, hãy sử dụng Utilities.formatDate(date, timeZone,
format) với định dạng chỉ định phần của ngày hoặc giờ bạn muốn và sử dụng AdsApp.currentAccount().getTimeZone() để lấy múi giờ của tài khoản.
Tạo đối tượng ngày từ chuỗi ngày đã định dạng
Bạn có thể tạo đối tượng ngày bằng cách truyền một chuỗi ngày đã định dạng vào hàm khởi tạo ngày. Ví dụ:
const date = new Date('February 17, 2021 13:00:00 -0500');
Hàm khởi tạo chỉ có thể phân tích cú pháp một số định dạng chuỗi ngày nhất định. Để đảm bảo chuỗi ngày tháng được phân tích cú pháp chính xác, hãy luôn cung cấp chuỗi đó ở định dạng MMMM dd, yyyy
HH:mm:ss Z.
Ví dụ: để tạo một đối tượng ngày cho buổi trưa hôm nay theo múi giờ của tài khoản hiện tại:
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);
Đừng sử dụng mẫu "z" để tạo chuỗi ngày sẽ được truyền vào hàm khởi tạo ngày, vì hàm khởi tạo không phải lúc nào cũng có thể phân tích cú pháp chuỗi ngày. Chỉ sử dụng mẫu "Z".
Toán học về ngày
Một số tập lệnh cần thực hiện phép tính đơn giản với ngày, chẳng hạn như tìm ngày X trước hoặc sau một ngày nhất định. Khi thực hiện phép toán ngày, hãy sử dụng getTime().
Việc gọi getTime() trên đối tượng ngày sẽ trả về số mili giây kể từ đầu ngày 1 tháng 1 năm 1970 (theo giờ UTC). Bạn có thể thực hiện phép tính trên giá trị này, sau đó áp dụng giá trị mới cho đối tượng ngày bằng cách sử dụng setTime() hoặc cung cấp giá trị đó dưới dạng tham số khi tạo đối tượng ngày mới.
Ví dụ:
const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);
Trong ví dụ này, yesterday cách đây chính xác 24 giờ.
Báo cáo
Khi truy xuất báo cáo bằng AdsApp.search(), truy vấn GAQL yêu cầu bạn chỉ định ngày theo định dạng yyyy-MM-dd (ví dụ: 2021-06-30 là ngày 30 tháng 6 năm 2021).
Tương tự, phương thức getStatsFor() có trên nhiều đối tượng tập lệnh Google Ads yêu cầu ngày được chỉ định theo cùng một định dạng. Sử dụng Utilities.formatDate(date, timeZone,
format) để định dạng đối tượng ngày theo định dạng này.
Ví dụ: để truy xuất báo cáo từ một đến ba ngày trước:
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'));
Bảng tính
Tập lệnh Google Ads thường ghi kết quả vào bảng tính, bao gồm cả các đối tượng ngày. Khi đặt một ô trong bảng tính bằng cách truyền một đối tượng ngày, múi giờ của bảng tính sẽ được dùng để diễn giải ngày đó. Ví dụ: giả sử chúng ta có một bảng tính có múi giờ được đặt thành Giờ Thái Bình Dương:
// Suppose today is February 17, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
Giá trị trong A1 sẽ là 17-Feb-21 10:00:00.
Để đảm bảo các đối tượng ngày được ghi vào bảng tính như mong đợi, hãy đặt múi giờ của bảng tính khớp với múi giờ của tài khoản Google Ads:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
Bạn cũng có thể đặt thời gian của bảng tính theo cách thủ công.