Эта страница переведена с помощью 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, 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\''));

В этих примерах часовой пояс указывался напрямую с помощью идентификатора часового пояса . Чтобы получить часовой пояс, связанный с аккаунтом 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' для создания строковых значений дат, которые будут передаваться в конструктор типа Date, поскольку конструктор не всегда сможет их обработать. Используйте только шаблон '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 Ads часто записывают данные в электронную таблицу, включая объекты дат. При задании значения в ячейке электронной таблицы путем передачи объекта даты, для интерпретации этой даты используется часовой пояс электронной таблицы. Например, предположим, у нас есть электронная таблица, в которой установлен тихоокеанский часовой пояс:

// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

Значение в ячейке A1 будет равно 17 февраля 2025 г., 10:00:00.

Чтобы гарантировать корректную запись объектов с датами в электронную таблицу, установите часовой пояс электронной таблицы в соответствии с часовым поясом вашего аккаунта Google Ads:

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

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