Скриптам Google Рекламы часто требуется работать с датами и временем. К типичным примерам использования относятся получение отчётов за определённый диапазон дат, планирование кампаний или групп объявлений на определённое время и вывод в электронную таблицу времени последнего запуска скрипта. В этом руководстве описаны важные концепции, распространённые ошибки и рекомендуемые подходы при работе с датами и временем в скриптах Google Рекламы.
Основные понятия
Для работы с датами и временем в скриптах 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);
Пользователи New Scripts часто путаются в том, как объекты даты обрабатывают часовые пояса. Естественно, но неверно рассматривать объект даты как время на часах в одном часовом поясе . Например, в приведённом выше фрагменте кода некоторые пользователи ошибочно предполагают, что date
действительна только в одном часовом поясе, а именно в том, который был использован для её создания со смещением -5 часов. В этом ошибочном представлении date
необходимо «конвертировать» для использования в других часовых поясах.
Вместо этого правильно рассматривать объект даты как конкретный момент времени, не зависящий от какого-либо часового пояса. Хотя конкретный момент отображается на часах в разных часовых поясах по-разному, это один и тот же момент. Например, рассмотрим следующий фрагмент:
// Create two date objects with different times and timezone 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('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\''));
В этих примерах часовой пояс указывается напрямую с помощью идентификатора часового пояса . Чтобы получить часовой пояс, связанный с аккаунтом 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)
.
Часовой пояс по умолчанию при создании объекта даты
При создании объекта даты с использованием строки, не содержащей смещения часового пояса, предполагается, что часовой пояс — Америка/Лос-Анджелес (тихоокеанское время), независимо от часового пояса, связанного с аккаунтом Google Ads . Например:
// Create a date without specifying the timezone 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()
для объекта даты возвращает количество миллисекунд с начала 1 января 1970 года по Гринвичу (UTC). Вы можете выполнить математические операции с этим значением, а затем применить новое значение к объекту даты с помощью 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
будет соответствовать 30 июня 2025 г.).
Аналогично, метод getStatsFor()
доступный во многих объектах скриптов Google Ads, требует указания дат в том же формате. Используйте 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 Рекламы часто записывают выходные данные в электронную таблицу, включая объекты даты. При задании ячейки в таблице путём передачи объекта даты для интерпретации этой даты используется часовой пояс таблицы. Например, предположим, что у нас есть таблица, часовой пояс которой установлен по тихоокеанскому времени:
// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
Значение в ячейке A1 будет 17-фев-25 10:00:00.
Чтобы гарантировать, что объекты даты будут записаны в электронную таблицу так, как вы ожидаете, установите часовой пояс электронной таблицы в соответствии с часовым поясом вашего аккаунта Google Ads:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
Вы также можете установить время в электронной таблице вручную .