处理日期和时间

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

您也可以手动设置电子表格的时间