Để thảo luận và đưa ra ý kiến phản hồi về các sản phẩm của chúng tôi, hãy tham gia kênh Discord chính thức của Google Ads trong máy chủ Cộng đồng quảng cáo và đo lường của Google.

Trang này được dịch bởi Cloud Translation API.

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

Các tập lệnh Google Ads thường cần phải 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ên 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 thời gian 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, những lỗi thường gặp và các phương pháp được đề 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

Để 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 JavaScript biểu thị 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, 2025 13:00:00 -0500');

// Create a copy of an existing date object.
let copy = new Date(date);

Người dùng mới của tập lệnh thường nhầm lẫn về 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 để nghĩ về đố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 tưởng 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 đó, date sẽ 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 để nghĩ về đối tượng ngày là một thời điểm cụ thể, độc lập với bất kỳ múi giờ nào. Mặc dù một thời điểm cụ thể được 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 thời điểm. 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, 2025 13:00:00 -0500');
const date2 = new Date('February 17, 2025 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 được "chuyển đổi" giữa các múi giờ. Thay vào đó, bạn có thể hiển thị ngày này 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 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, 2025 13:00:00 -0500');

// February 17, 2025 13:00:00 -0500
console.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2025 10:00:00 -0800
console.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2025-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 timezone ID (mã múi giờ). Để truy xuất múi giờ được 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

Sau đây là một số lỗi thường gặp liên quan đến ngày.

Múi giờ mặc định khi ghi nhật ký đối tượng ngày

Khi ghi trực tiếp một đối tượng ngày bằng Logger.log(), đối tượng đó 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, 2025 13:00:00 -0500');

// Mon Feb 17 10:00:00 GMT-08:00 2025
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 cho mục đích ghi nhật ký hoặc 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, 2025 13:00:00');

// Mon Feb 17 13:00:00 GMT-08:00 2025
console.log(date);

Khi tạo một đối tượng ngày bằng chuỗi, hãy luôn thêm độ lệch múi giờ để đảm bảo đối tượng ngày biểu thị 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

Các đố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ờ đượ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 trong 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, giờ hoặc phút cho một đối tượng ngày theo múi giờ của tài khoản, hãy sử dụng Utilities.formatDate(date, timeZone, format) với một định dạng chỉ định phần ngày hoặc giờ mà bạn muốn, đồng thời 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 được định dạng

Bạn có thể tạo một đối tượng ngày bằng cách truyền một chuỗi ngày được định dạng vào hàm khởi tạo ngày. Ví dụ:

const date = new Date('February 17, 2025 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 ngày ở đị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 đến hàm khởi tạo ngày, vì hàm khởi tạo sẽ không phải lúc nào cũng phân tích cú pháp được chuỗi đó. Chỉ sử dụng hình mở khoá "Z".

Phép toán 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 ngày trước hoặc sau một ngày nhất định X ngày. Khi thực hiện phép toán về 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 theo giờ UTC. Bạn có thể thực hiện phép toán 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ị đó làm 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 là chính xác 24 giờ trước.

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 ở định dạng yyyy-MM-dd (ví dụ: 2025-06-30 sẽ là ngày 30 tháng 6 năm 2025).

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 bạn chỉ định ngày 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ừ 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

Các tập lệnh Google Ads thường ghi dữ liệu đầu ra vào một bảng tính, bao gồm cả các đối tượng ngày. Khi bạn đặ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 đặt theo múi giờ Thái Bình Dương:

// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

Giá trị trong ô A1 sẽ là 17/2/2025 10:00:00.

Để đảm bảo các đối tượng ngày được ghi vào bảng tính như bạn mong đợi, hãy đặt múi giờ của bảng tính sao cho 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.