Tập lệnh Google Ads thường cần phải hoạt động với ngày và giờ. Các trường hợp sử dụng phổ biến bao gồm việc truy xuất báo cáo cho một phạm vi ngày cụ thể, lập lịch để chiến dịch hoặc nhóm quảng cáo chạy vào những thời điểm cụ thể và xuất ra bảng tính vào thời điểm tập lệnh chạy gần đây nhất. Hướng dẫn này mô tả các khái niệm quan trọng, lỗi phổ biến và phương pháp đề xuất khi xử lý ngày và giờ trong tập lệnh Google Ads.
Khái niệm cơ bản
Để làm việc với 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 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 nhầm lẫn bởi cách các đố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 để coi đối tượng ngày là giờ trên một đồng hồ trong một múi giờ duy nhất. Ví dụ: trong đoạn mã trên, một số người dùng nhầm lẫn rằng date chỉ hợp lệ ở một múi giờ, cụ thể là múi giờ có chênh lệch -5 giờ được dùng để tạo múi giờ. Trong chế độ xem bị nhầm lẫn đó, date cần được "chuyển đổi" để sử dụng ở các múi giờ khác.
Thay vào đó, cách chính xác để xem xét đối tượng ngày là một khoảnh khắc cụ thể trong thời gian không phụ thuộc vào mọi múi giờ. Mặc dù một khoảnh khắc cụ thể được hiển thị theo cách khác nhau trên các đồng hồ ở các múi giờ khác nhau, nhưng đó vẫn là cùng một khoảnh khắc. Chẳng hạn, hãy xem xét đoạn mã này:
// 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 đại diện cho một thời điểm cụ thể, nên đối tượng này không cần phải "chuyển đổi" giữa các múi giờ. Thay vào đó, kết quả hiển thị có thể được kết xuất dưới dạng chuỗi được định dạng theo múi giờ cụ thể.
Để hiển thị ngày dưới dạng 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 trực tiếp chỉ định múi giờ bằng mã 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 của bạn, 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ý một đối tượng ngày bằng Logger.log(), đối tượng đó sẽ được kết xuất theo đị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ủa tài khoản Google Ads. Nếu bạn muốn hiển thị đối tượng ngày dưới dạng chuỗi bằ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 chênh lệch múi giờ, múi giờ được giả định là Mỹ/Los_Angeles (giờ Thái Bình Dương), bất kể múi giờ của tài khoản Google Ads là múi giờ nào. 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 giá trị chênh 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 phương thức đối tượng ngày
Các đối tượng ngày trong 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()
API này cũng bao gồm các dữ liệu tương đương set___() của các phương thức này (ví dụ:
setMonth()) và getTimezoneOffset().
Trong tập lệnh Google Ads, múi giờ mặc định là Mỹ/Los_Angeles (theo giờ Thái Bình Dương), bất kể múi giờ của tài khoản Google Ads này là múi giờ nào. Do đó, trừ phi tài khoản Google Ads của bạn ở múi giờ này, bạn thường không nên 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) theo định dạng chỉ định phần ngày hoặc giờ mà 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ừ một chuỗi ngày được định dạng
Bạn có thể tạo đối tượng ngày bằng cách chuyển một chuỗi ngày đã được định dạng đến 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 đượ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 đối tượng ngày cho 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);
Không sử dụng mẫu 'z' để tạo các chuỗi ngày sẽ được chuyển đến 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 theo ngày
Một số tập lệnh cần thực hiện phép toán đơn giản với ngày, chẳng hạn như tìm một ngày X ngày trước hoặc sau một ngày nhất định. Khi thực hiện phép tính ngày, hãy sử dụng getTime().
Việc gọi getTime() trên một đối tượng ngày sẽ trả về số mili giây kể từ đầu ngày 1 tháng 1 năm 1970 (giờ UTC). Bạn có thể thực hiện toán học 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
thông 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 chính xác là 24 giờ trước.
Báo cáo
Khi truy xuất một báo cáo bằng AdsApp.search(), truy vấn GAQL yêu cầu bạn phải chỉ định ngày ở định dạng yyyy-MM-dd (ví dụ: 2021-06-30 sẽ là ngày 30 tháng 6 năm 2021).
Tương tự, phương thức getStatsFor() có sẵn trên nhiều đối tượng
tập lệnh Google Ads yêu cầu bạn phải chỉ định ngày ở cùng định dạng. Sử dụng Utilities.formatDate(date, timeZone,
format) để định dạng đối tượng ngày ở đị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 một 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 là 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à 10:00:00 17-21/2/2021.
Để đảm bảo đối tượng ngày được ghi vào bảng tính như bạn mong muốn, 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 cho bảng tính theo cách thủ công.