此页面由 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);

与 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 脚本中，默认时区为 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() 会返回自世界协调时间 (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 小时前。

报告

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

为了确保将日期对象写入您所需的电子表格，请将电子表格的时区设置为与您 Google Ads 账户的时区一致：

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

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