Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

处理日期和时间

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, 2025 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 time zone offsets.
const date1 = new Date('February 17, 2025 13:00:00 -0500');
const date2 = new Date('February 17, 2025 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, 2025 13:00:00 -0500');

// February 17, 2025 13:00:00 -0500
console.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2025 10:00:00 -0800
console.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2025-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, 2025 13:00:00 -0500');

// Mon Feb 17 10:00:00 GMT-08:00 2025
console.log(date);

默认时区为 America/Los_Angeles（太平洋时间），无论与 Google Ads 账号关联的时区是什么。如果您想使用自定义格式和时区将日期对象呈现为字符串以进行记录或其他用途，请始终使用 Utilities.formatDate(date, timeZone, format)。

创建日期对象时的默认时区

使用不提供时区偏移量的字符串创建日期对象时，系统会假定时区为 America/Los_Angeles（太平洋时间），无论与 Google Ads 账号关联的时区是什么。例如：

// Create a date without specifying the time zone offset.
const date = new Date('February 17, 2025 13:00:00');

// Mon Feb 17 13:00:00 GMT-08:00 2025
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, 2025 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格式指定日期（例如，2025-06-30 表示 2025 年 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, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

A1 中的值将为 17-Feb-25 10:00:00。

为确保日期对象按预期写入电子表格，请将电子表格的时区设置为与 Google Ads 账号的时区一致：

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

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