使用日期和時間

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, 2021 13:00:00 -0500');

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

新手 Script 使用者經常會對日期物件處理時區的方式感到困惑。將日期物件視為「單一時區的時間時間」，但「不正確」會視為日期物件。舉例來說，在上述程式碼片段中，部分使用者誤以為 date 只在一個時區有效，也就是用來建立該時區的 -5 小時時差。在錯誤的觀點中，date 需要經過「轉換」才能在其他時區使用。

相反地，正確的日期物件思考方式，是將日期物件視為不受任何時區影響的特定時間點。雖然不同時區的時鐘會顯示不同的特定時刻，但時間本身並無差異。舉例來說，請參考以下程式碼片段：

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

注意：在內部，JavaScript 會以自世界標準時間 1970 年 1 月 1 日起經過的毫秒數，表示日期物件。

日期物件代表特定時間點，因此不需要跨時區「轉換」。而是以字串格式呈現，並根據特定時區格式化。

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

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

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

常見陷阱

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

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

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

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

預設時區為 America/Los_Angeles (太平洋時間)，不論 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, 2021 13:00:00');

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

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

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

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

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

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

在 Google Ads 指令碼中，預設時區為 America/Los_Angeles (太平洋時間)，不論 Google Ads 帳戶連結的時區為何。因此，除非 Google Ads 帳戶位在這個時區，否則一般來說請避免使用這些方法。

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

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

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

const date = new Date('February 17, 2021 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 格式指定日期 (例如 2021-06-30 為 2021 年 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, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

A1 中的值會是 17-Feb-21 10:00:00。

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

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

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