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

Скрипты AdWords часто работают с датами и временем. Например, это происходит, когда нужно получить отчеты по определенному диапазону дат, настроить расписание для кампаний или групп объявлений и добавить в таблицу время последнего запуска скрипта. В этом руководстве рассматриваются основные понятия, случаи, требующие особого внимания, и рекомендуемые подходы при работе с датами и временем в скриптах AdWords.

Основные понятия

Для работы с датами и временем в скриптах AdWords необходимо использовать встроенный объект даты. Этот объект JavaScript представляет определенный момент времени. Его можно создать несколькими способами.

// Create a date object for the current date and time.
var now = new Date();

// Create a date object for a past date and time using a formatted string.
var date = new Date('February 17, 2016 13:00:00 -0500');

// Create a copy of an existing date object.
var copy = new Date(date);

Новым пользователям иногда сложно понять, как в этих объектах обрабатываются часовые пояса. Неправильно думать, что объект даты представляет собой время в определенном часовом поясе. Например, некоторые пользователи ошибочно считают, что переменная date в приведенном выше фрагменте кода действительна только в часовом поясе со смещением -5 часов, который использовался при ее создании. Поэтому они думают, что переменную date необходимо преобразовать для использования в других часовых поясах.

В действительности объект даты представляет собой определенный момент времени, не зависящий от часового пояса. Хотя он соответствует разным значениям времени в разных часовых поясах, это один и тот же момент. Например, рассмотрим следующий фрагмент кода:

// Create two date objects with different times and timezone offsets.
var date1 = new Date('February 17, 2016 13:00:00 -0500');
var date2 = new Date('February 17, 2016 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.
Logger.log(date1.getTime() == date2.getTime());

// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
Logger.log(date1 == date2);

Поскольку объект даты соответствует определенному моменту времени, его не требуется преобразовывать в другие часовые пояса. Вместо этого его следует обрабатывать как строку, которая может быть отформатирована для определенного часового пояса.

Чтобы сформировать строку даты определенного формата и часового пояса, необходимо использовать метод Utilities.formatDate(date, timeZone, format). Рассмотрим несколько примеров.

var date = new Date('February 17, 2016 13:00:00 -0500');

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

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

// 2016-02-17T18:00:00.000Z
Logger.log(Utilities.formatDate(date, 'Etc/GMT', 'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\''));

В этих примерах использовался идентификатор часового пояса. Чтобы узнать, какой часовой пояс связан с аккаунтом AdWords, в котором выполняется скрипт, следует использовать метод AdWordsApp.currentAccount().getTimeZone().

Случаи, требующие особого внимания

Часовой пояс по умолчанию при записи объекта даты

При записи объекта даты с помощью метода Logger.log() он выводится в формате и часовом поясе по умолчанию. Рассмотрим пример.

var date = new Date('February 17, 2016 13:00:00 -0500');

// Wed Feb 17 10:00:00 GMT-08:00 2016
Logger.log(date);

По умолчанию используется тихоокеанское время независимо от того, какой часовой пояс связан с аккаунтом AdWords. Если вам нужно сформировать объект даты в виде строки с использованием особого формата и часового пояса для записи или других целей, всегда используйте метод Utilities.formatDate(date, timeZone, format).

Часовой пояс по умолчанию при создании объекта даты

При создании объекта даты с использованием строки без указания часового пояса по умолчанию используется тихоокеанское время независимо от того, какой часовой пояс связан с аккаунтом AdWords. Рассмотрим пример.

// Create a date without specifying the timezone offset.
var date = new Date('February 17, 2016 13:00:00');

// Wed Feb 17 13:00:00 GMT-08:00 2016
Logger.log(date);

При создании объекта даты с использованием строки всегда указывайте часовой пояс, чтобы объект даты представлял нужный момент времени.

Часовой пояс по умолчанию в методах объекта даты

Объекты даты в JavaScript содержат несколько методов, где используется часовой пояс по умолчанию, в том числе getFullYear(), getMonth(), getDate(), getDay(), getHours() и getMinutes(), соответствующие им методы set___(), а также getTimezoneOffet(). В скриптах AdWords по умолчанию используется тихоокеанское время независимо от того, какой часовой пояс связан с аккаунтом AdWords. Поэтому если в вашем аккаунте не используется этот часовой пояс, следует избегать этих методов.

Вместо этого для получения года, месяца, даты, дня, часов и минут объекта даты в своем часовом поясе следует использовать метод Utilities.formatDate(date, timeZone, format) с форматом, указывающим нужную часть даты или времени, а также метод AdWordsApp.currentAccount().getTimeZone() для получения часового пояса аккаунта.

Создание объекта даты из форматированной строки даты

Вы можете создать объект даты, передав форматированную строку в конструктор. Рассмотрим пример.

var date = new Date('February 17, 2016 13:00:00 -0500');

Конструктор может обрабатывать только некоторые форматы строк даты. Чтобы обеспечить правильную обработку строки даты, всегда указывайте ее в формате MMMM dd, yyyy HH:mm:ss Z.

Рассмотрим пример создания объекта даты для полудня текущего дня в часовом поясе аккаунта.

var now = new Date();
var timeZone = AdWordsApp.currentAccount().getTimeZone();
var noonString = Utilities.formatDate(now, timeZone,
                                      'MMMM dd, yyyy 12:00:00 Z')
var noon = new Date(noonString);

Не используйте шаблон z для создания строк даты, которые будут передаваться в конструктор даты, поскольку он не всегда может их обработать. Используйте только шаблон Z.

Математические операции с датами

В некоторых скриптах необходимо выполнять простые математические операции с датами, например расчет даты, которая на X дней предшествует указанной. Выполняя такие операции, всегда используйте метод getTime(). При вызове метода getTime() для объекта даты возвращается количество миллисекунд с 1 января 1970 года по всемирному координированному времени. Вы можете выполнять с этим значением математические операции, а затем применять полученное значение к объекту даты, используя метод setTime() или указывая его в качестве параметра при создании нового объекта даты.

Рассмотрим пример.

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

Здесь yesterday содержит значение, на 24 часа предшествующее текущему времени.

Отчетность

При получении отчета с использованием метода AdWordsApp.report(query, optArgs) AWQL-запрос требует, чтобы даты были указаны в виде 8-значного целого числа (YYYYMMDD). То же самое относится к методу getStatsFor(), доступному во многих объектах скриптов AdWords. Для преобразования объекта даты в этот формат используйте метод Utilities.formatDate(date, timeZone, format).

Рассмотрим, как получить отчет для трех предшествующих дней.

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
var to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);

var timeZone = AdWordsApp.currentAccount().getTimeZone();
var report = AdWordsApp.report(
  'SELECT CampaignName, Clicks ' +
  'FROM   CAMPAIGN_PERFORMANCE_REPORT ' +
  'DURING ' + Utilities.formatDate(from, timeZone, 'yyyyMMdd') + ','
            + Utilities.formatDate(to, timeZone, 'yyyyMMdd'));

Таблицы

Скрипты AdWords часто записывают результаты работы, в том числе объекты даты, в таблицу. При записи значения ячейки путем передачи объекта даты используется часовой пояс таблицы. Например, предположим, что в таблице задано тихоокеанское время.

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

В ячейке A1 будет значение 17-Feb-16 10:00:00.

Чтобы объекты даты правильно записывались в таблицу, задайте в таблице часовой пояс аккаунта AdWords.

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

Кроме того, можно задать время таблицы вручную.

Оставить отзыв о...

Текущей странице
Скрипты AdWords
Скрипты AdWords