本頁面由 Cloud Translation API 翻譯而成。

使用日期和時間

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

新的指令碼使用者通常會因為日期物件處理時區的方式感到困惑。將日期物件視為單一時區時鐘的時間，是一種自然但「不正確」的方式。例如，在上方的程式碼片段中，部分使用者誤以為 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);

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

如要將日期算繪為特定格式和時區的字串，請使用 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」模式。

日期數學

部分指令碼需要執行具有日期的簡易數學運算，例如找出特定日期之前或之後的日期。執行日期數學運算時，請使用 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() 擷取報表時，您必須以 yyyy-MM-dd 格式指定日期 (例如 2021-06-30 為 2021 年 6 月 30 日)。

同樣地，許多 Google Ads 指令碼物件可用的 getStatsFor() 方法也需要使用相同格式指定日期。請使用 Utilities.formatDate(date, timeZone, format) 將日期物件的格式設為此格式。

舉例來說，如要擷取 1-3 天前的報表：

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 中的值會是 2021 年 2 月 17 日 10:00:00。

如要確保日期物件會按預期寫入試算表，請依據您 Google Ads 帳戶的時區設定試算表的時區：

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

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