本頁面由 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」。

日期運算

部分指令碼需要使用日期執行簡單的數學運算，例如在特定日期前或後找出日期 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-2 月 21 日 10:00:00。

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

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

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