Google Apps Script: Как получить текущее время?

Введение в получение текущего времени в Google Apps Script

Google Apps Script позволяет автоматизировать множество задач, связанных с приложениями Google Workspace. Одной из базовых потребностей при этом является получение текущего времени. Это может потребоваться для логирования, создания триггеров, добавления временных меток к данным и многого другого.

Зачем нужно получать текущее время в Google Apps Script?

Получение текущего времени необходимо для:

• Логирования операций: Отслеживание времени выполнения скриптов и отдельных операций.
• Автоматизации задач по расписанию: Запуск функций в определенное время.
• Анализа данных: Добавление временных меток к данным для последующего анализа временных рядов.
• Персонализации: Отображение информации, зависящей от текущего времени (например, приветствия).

Обзор основных подходов и инструментов

Для получения текущего времени в Google Apps Script используются:

• Объект Date: Встроенный объект JavaScript для работы с датой и временем.
• Метод getTime(): Возвращает количество миллисекунд, прошедших с 1 января 1970 года (Unix timestamp).
• Utilities.formatDate(): Функция для форматирования даты и времени в соответствии с заданным шаблоном и часовым поясом.

Использование объекта Date для получения текущего времени

Объект Date — основной инструмент для работы со временем в Google Apps Script. Он позволяет получить текущее время, манипулировать датами и временем, а также форматировать их.

Создание нового объекта Date

Самый простой способ получить текущее время – создать новый объект Date без аргументов:

/**
 * Получает текущее время.
 * @return {Date} Текущая дата и время.
 */
function getCurrentTime() {
  // Создаем новый объект Date.
  const now = new Date();
  return now;
}

// Пример использования:
const currentTime = getCurrentTime();
Logger.log(currentTime); // Выведет текущую дату и время в консоль.

Получение текущего времени в миллисекундах с помощью getTime()

Метод getTime() возвращает количество миллисекунд, прошедших с начала эпохи Unix (1 января 1970 года, 00:00:00 UTC). Это полезно для сравнения временных меток и выполнения математических операций с датами.

/**
 * Получает текущее время в миллисекундах.
 * @return {number} Текущее время в миллисекундах.
 */
function getCurrentTimeMillis() {
  // Получаем текущую дату и время.
  const now = new Date();
  // Возвращаем количество миллисекунд.
  return now.getTime();
}

// Пример использования:
const currentTimeMillis = getCurrentTimeMillis();
Logger.log(currentTimeMillis); // Выведет текущее время в миллисекундах.

Преобразование временной метки в объект Date

Иногда возникает необходимость преобразовать временную метку (количество миллисекунд) обратно в объект Date. Это можно сделать, передав временную метку в качестве аргумента конструктору Date.

/**
 * Преобразует временную метку в объект Date.
 * @param {number} timestamp Временная метка в миллисекундах.
 * @return {Date} Объект Date, представляющий временную метку.
 */
function timestampToDate(timestamp) {
  // Создаем объект Date из временной метки.
  const date = new Date(timestamp);
  return date;
}

// Пример использования:
const timestamp = 1678886400000; // Пример временной метки (15 марта 2023)
const date = timestampToDate(timestamp);
Logger.log(date); // Выведет дату, соответствующую временной метке.

Форматирование даты и времени в Google Apps Script

Объект Date содержит информацию о дате и времени, но для отображения этой информации в удобном для пользователя формате необходимо использовать форматирование.

Использование Utilities.formatDate() для форматирования даты и времени

Функция Utilities.formatDate() позволяет форматировать дату и время в соответствии с заданным шаблоном, часовым поясом и локалью.

/**
 * Форматирует дату и время в соответствии с заданным шаблоном.
 * @param {Date} date Объект Date для форматирования.
 * @param {string} timeZone Часовой пояс.
 * @param {string} format Шаблон форматирования.
 * @return {string} Отформатированная строка даты и времени.
 */
function formatDate(date, timeZone, format) {
  // Форматируем дату и время.
  const formattedDate = Utilities.formatDate(date, timeZone, format);
  return formattedDate;
}

Примеры различных форматов даты и времени

// Получаем текущую дату и время.
const now = new Date();

// Определяем часовой пояс.
const timeZone = Session.getTimeZone();

// Примеры различных форматов:
Logger.log(formatDate(now, timeZone, 'yyyy-MM-dd HH:mm:ss')); // 2023-10-27 10:30:00
Logger.log(formatDate(now, timeZone, 'dd/MM/yyyy')); // 27/10/2023
Logger.log(formatDate(now, timeZone, 'MMMM d, yyyy')); // October 27, 2023
Logger.log(formatDate(now, timeZone, 'h:mm a')); // 10:30 AM

Указание часового пояса

Важно указывать правильный часовой пояс, чтобы дата и время отображались корректно. Можно использовать Session.getTimeZone() для получения текущего часового пояса скрипта или указать конкретный часовой пояс, например, 'America/Los_Angeles'. Список доступных часовых поясов можно найти в документации IANA.

Работа с часовыми поясами

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

Получение текущего часового пояса скрипта

Для получения текущего часового пояса, используемого скриптом, можно использовать Session.getTimeZone():

/**
 * Получает текущий часовой пояс скрипта.
 * @return {string} Текущий часовой пояс.
 */
function getCurrentTimeZone() {
  // Получаем текущий часовой пояс скрипта.
  const timeZone = Session.getTimeZone();
  return timeZone;
}

// Пример использования:
const currentTimeZone = getCurrentTimeZone();
Logger.log(currentTimeZone); // Выведет текущий часовой пояс скрипта.

Преобразование времени между разными часовыми поясами

Google Apps Script не предоставляет встроенных функций для преобразования времени между разными часовыми поясами напрямую. Однако, это можно реализовать, используя сторонние библиотеки или API, либо написав собственный код, учитывающий разницу во времени между часовыми поясами.

Простейший способ — использовать Utilities.formatDate() для форматирования даты в целевом часовом поясе. Например:

const now = new Date();
const targetTimeZone = 'America/Los_Angeles';
const formattedDate = Utilities.formatDate(now, targetTimeZone, 'yyyy-MM-dd HH:mm:ss z');
Logger.log(formattedDate);

Примеры использования текущего времени в Google Apps Script

Автоматическое добавление временной метки к данным Google Sheets

/**
 * Добавляет временную метку в активную ячейку в Google Sheets.
 */
function addTimestampToSheet() {
  // Получаем активный лист.
  const sheet = SpreadsheetApp.getActiveSheet();
  // Получаем активную ячейку.
  const cell = sheet.getActiveCell();
  // Получаем текущую дату и время.
  const now = new Date();
  // Форматируем дату и время.
  const timeZone = Session.getTimeZone();
  const formattedDate = Utilities.formatDate(now, timeZone, 'yyyy-MM-dd HH:mm:ss');
  // Записываем отформатированную дату и время в ячейку.
  cell.setValue(formattedDate);
}

Создание триггеров, срабатывающих в определенное время

/**
 * Создает триггер, срабатывающий ежедневно в 9:00 утра.
 */
function createDailyTrigger() {
  // Удаляем существующие триггеры с тем же названием функции.
  const triggers = ScriptApp.getProjectTriggers();
  for (const trigger of triggers) {
    if (trigger.getHandlerFunction() === 'myFunction') {
      ScriptApp.deleteTrigger(trigger);
    }
  }

  // Создаем триггер, срабатывающий ежедневно в 9:00 утра.
  ScriptApp.newTrigger('myFunction')
    .timeBased()
    .atHour(9)
    .everyDays(1)
    .create();
}

/**
 * Функция, которая будет выполняться по триггеру.
 */
function myFunction() {
  Logger.log('Функция выполнена по триггеру в: ' + new Date());
  // Добавьте здесь код, который нужно выполнить по расписанию.
}

Логирование событий с указанием времени

/**
 * Логирует событие с указанием текущего времени.
 * @param {string} eventName Название события.
 * @param {string} message Сообщение.
 */
function logEvent(eventName, message) {
  // Получаем текущую дату и время.
  const now = new Date();
  // Форматируем дату и время.
  const timeZone = Session.getTimeZone();
  const formattedDate = Utilities.formatDate(now, timeZone, 'yyyy-MM-dd HH:mm:ss');
  // Формируем строку лога.
  const logString = `[${formattedDate}] ${eventName}: ${message}`;
  // Логируем строку в консоль.
  Logger.log(logString);
}

// Пример использования:
logEvent('User Login', 'User John Doe logged in successfully.');