Работа с датами и временем

Скриптам 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());

Вы также можете установить время в электронной таблице вручную .