使用日期和時間

Google Ads 腳本通常需要處理日期和時間。常見用途包括擷取特定日期範圍的報表、排定廣告活動或廣告群組在特定時間放送，以及將指令碼上次執行的時間輸出至試算表。本指南說明在 Google Ads 腳本中使用日期和時間時的重要概念、常見陷阱和建議做法。

基本概念

如要在 Google Ads 腳本中使用日期和時間，請使用 JavaScript 內建的日期物件。JavaScript 日期物件代表特定時間點。 建立新日期物件的方式如下：

// 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);

新版 Apps Script 使用者經常對日期物件處理時區的方式感到困惑。以單一時區的時鐘時間來思考日期物件，是自然但不正確的方式。舉例來說，在上方的程式碼片段中，部分使用者會誤以為 date 僅在一個時區有效，也就是建立該時區時使用的時區 (時差為 -5 小時)。在該錯誤檢視畫面中，date 需要「轉換」才能在其他時區使用。

正確的做法是將日期物件視為特定時間點，與任何時區無關。雖然不同時區的時鐘顯示的時間不同，但其實是同一時刻。舉例來說，請參考以下程式碼片段：

// 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);

由於日期物件代表特定時間點，因此不需要跨時區「轉換」。而是以格式化為特定時區的字串。

如要以特定格式和時區將日期算繪為字串，請使用 Utilities.formatDate(date, timeZone, format)。例如：

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\''));

這些範例直接使用時區 ID 指定時區。 如要擷取與執行指令碼的 Google Ads 帳戶相關聯的時區，請使用 AdsApp.currentAccount().getTimeZone()。

常見陷阱

以下列舉幾個常見的日期問題。

記錄日期物件時的預設時區

使用 Logger.log() 直接記錄日期物件時，系統會使用預設格式和時區進行轉譯。例如：

const date = new Date('February 17, 2025 13:00:00 -0500');

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

預設時區為美國/洛杉磯 (太平洋時間)，與 Google Ads 帳戶的時區無關。如要使用自訂格式和時區，將日期物件算繪為字串，以供記錄或其他用途，請一律使用 Utilities.formatDate(date, timeZone, format)。

建立日期物件時的預設時區

使用未提供時區偏移的字串建立日期物件時，系統會假設時區為 America/Los_Angeles (太平洋時間)，無論與 Google Ads 帳戶相關聯的時區為何。例如：

// 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);

使用字串建立日期物件時，請務必加入時區偏移量，確保日期物件代表您實際想要的時刻。

日期物件方法中的預設時區

JavaScript 日期物件有幾種方法會採用預設時區，例如：

  • getFullYear()
  • getMonth()
  • getDate()
  • getDay()
  • getHours()
  • getMinutes()

這也包括這些方法的 set___() 對等項目 (例如 setMonth()) 和 getTimezoneOffset()。

在 Google Ads 指令碼中，預設時區為美洲/洛杉磯 (太平洋時間)，與 Google Ads 帳戶的時區無關。 因此，除非您的 Google Ads 帳戶位於這個時區，否則一般應避免使用這些方法。

如要取得帳戶時區中日期物件的年、月、日、星期、小時或分鐘，請使用 Utilities.formatDate(date, timeZone, format)，並指定所需日期或時間部分，然後使用 AdsApp.currentAccount().getTimeZone() 取得帳戶時區。

從格式化的日期字串建立日期物件

您可以將格式化的日期字串傳遞至日期建構函式，藉此建立日期物件。例如：

const date = new Date('February 17, 2025 13:00:00 -0500');

建構函式只能剖析特定日期字串格式。為確保系統正確剖析日期字串，請一律以 MMMM dd, yyyy HH:mm:ss Z 格式提供。

舉例來說，如要為目前帳戶時區的今天中午建構日期物件，請執行下列操作：

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);

請勿使用「z」模式建立日期字串，並傳遞至日期建構函式，因為建構函式不一定能剖析該字串。只能使用「Z」字型。

日期運算

部分指令碼需要對日期執行簡單的數學運算，例如找出指定日期前或後 X 天的日期。執行日期運算時，請使用 getTime()。 在日期物件上呼叫 getTime() 會傳回自世界標準時間 1970 年 1 月 1 日起經過的毫秒數。您可以對這個值執行數學運算，然後使用 setTime() 將新值套用至日期物件，或在建立新的日期物件時，將新值做為參數提供。

例如：

const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

在本例中，yesterday 是 24 小時前。

報表

使用 AdsApp.search() 擷取報表時，GAQL 查詢必須以 yyyy-MM-dd 格式指定日期 (例如 2025-06-30 代表 2025 年 6 月 30 日)。

同樣地，許多 Google Ads 指令碼物件提供的 getStatsFor() 方法也需要以相同格式指定日期。使用 Utilities.formatDate(date, timeZone, format) 以這個格式設定日期物件的格式。

舉例來說，如要擷取一到三天前的報表：

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'));

試算表

Google Ads 指令碼通常會將輸出內容 (包括日期物件) 寫入試算表。透過傳遞日期物件設定試算表中的儲存格時，系統會使用試算表的時區解讀該日期。舉例來說，假設我們有一份試算表，時區設為太平洋時區：

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

A1 儲存格中的值會是 2025 年 2 月 17 日上午 10:00:00。

為確保日期物件能如預期寫入試算表，請將試算表的時區設為與 Google Ads 帳戶時區一致：

spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());

你也可以手動設定試算表的時間。