Làm việc với ngày và giờ

Các tập lệnh Google Ads thường cần xử lý 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ập lịch chiến dịch hoặc các nhóm quảng cáo chạy vào những thời điểm cụ thể và xuất thời gian ra bảng tính tập lệnh chạy lần gần đây nhất. 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 làm việc với ngày và giờ trong tập lệnh Google Ads.

Các 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 ngày tích hợp trong JavaScript . Đối tượng ngày trong JavaScript đại diện cho một thời điểm cụ thể. Có 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ờ. Đáp tự nhiên nhưng không chính xác khi nghĩ về một đối tượng ngày là thời gian trên đồng hồ ở 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ệ trong một múi giờ, cụ thể là múi giờ với độ lệch -5 giờ được dùng để tạo múi giờ đó. Trong lúc nhầm lẫn đó chế độ xem, date cần được "chuyển đổi" để sử dụng trong các múi giờ khác.

Thay vào đó, cách chính xác để suy nghĩ về một đối tượng ngày tháng là một đối tượng cụ thể từng thời điểm không phụ thuộc vào múi giờ. 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);

Lưu ý: Trong nội bộ, JavaScript biểu thị đối tượng ngày dưới dạng số mili giây kể từ ngày 1 tháng 1 năm 1970 theo giờ UTC.

Vì một đố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 được "chuyển đổi" theo 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ý một đố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 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 đố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 thể hiện đúng thời điểm mà bạn 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 pháp sau' set___() tương đương (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ờ được liên kết với tài khoản Google Ads. Do đó, trừ phi tài khoản Google Ads của bạn nằm ở múi giờ này, bạn nên thường tránh sử dụng các phương pháp này.

Để biết 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) có định dạng chỉ định phần ngày hoặc giờ mà bạn muốn và sử dụng AdsApp.currentAccount().getTimeZone() để biết múi giờ trong tài khoản của bạn.

Tạo đối tượng ngày 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 vào đối tượng ngày đó hàm khởi tạo. 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 trong tài khoản hiện tại múi giờ:

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 chữ "z" mẫu để tạo các chuỗi ngày sẽ được chuyển đến một ngày hàm khởi tạo, 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. Chỉ sử dụng chữ '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 toán với 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 một khi tạo một đố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 một báo cáo bằng AdsApp.search(), truy vấn GAQL yêu cầu 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ó trên nhiều tập lệnh Google Ads các đối tượng yêu cầu chỉ định ngày theo cùng đị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ừ 1 đến 3 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 chuyển đối tượng ngày, múi giờ của bảng tính được dùng để diễn giải ngày đó. Ví dụ: giả sử chúng ta có 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à 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 cho bảng tính theo cách thủ công.