此页面由 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 脚本中，与 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());

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