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);
与 Google Ads 账户的关联时区无关,默认时区为美国/洛杉矶(太平洋时间)。如果您希望使用自定义格式和时区将日期对象渲染为字符串,以用于日志记录或其他目的,请始终使用 Utilities.formatDate(date, timeZone,
format)
。
创建日期对象时的默认时区
如果使用不提供时区偏移量的字符串创建日期对象,则与 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 脚本中,与 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()
将返回自世界协调时间 (UTC) 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 小时前。
Reporting(报告)
使用 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());
您也可以手动设置电子表格的时间。