Как настроить триггер календаря в Google Apps Script?

Что такое триггеры и зачем они нужны?

Триггеры в Google Apps Script – это специальные механизмы, которые позволяют автоматически запускать функции в ответ на определенные события. Представьте, что вам нужно автоматически отправлять уведомления каждый раз, когда в вашем календаре появляется новое событие. Без триггеров вам бы пришлось вручную запускать скрипт каждый раз. Триггеры автоматизируют этот процесс, делая ваши скрипты более эффективными и отзывчивыми.

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

Типы триггеров, доступные для Google Calendar

Для Google Calendar доступны следующие основные типы триггеров:

• On event creation: Запускается при создании нового события в календаре.
• On event change: Запускается при изменении существующего события в календаре (например, изменение времени, описания, участников).
• On event deletion: Запускается при удалении события из календаря.

Эти триггеры могут быть настроены как вручную через редактор Apps Script, так и программно с использованием Script Service.

Предварительные требования: настройка Google Apps Script

Прежде чем начать использовать триггеры, убедитесь, что у вас есть доступ к Google Apps Script. Вы можете получить доступ к редактору Apps Script, открыв Google Calendar, выбрав «Инструменты» -> «Редактор скриптов». Также убедитесь, что у вас есть базовые знания JavaScript и понимание работы с Google Calendar API.

Создание триггера, активируемого при изменении Календаря

Функция, которая будет выполняться при срабатывании триггера

Сначала определим функцию, которая будет выполняться при срабатывании триггера. Например, функция, которая записывает информацию о событии в Google Sheets:

/**
 * @OnlyCurrentDoc
 */

/**
 * Logs event details to a spreadsheet when a calendar event is created.
 *
 * @param {GoogleAppsScript.Events.CalendarEvent} e The event object passed to the trigger.
 */
function logCalendarEvent(e: GoogleAppsScript.Events.CalendarEvent): void {
  // Get the spreadsheet.
  const ss: GoogleAppsScript.Spreadsheet.Spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  const sheet: GoogleAppsScript.Spreadsheet.Sheet = ss.getSheetByName("Event Log") || ss.insertSheet("Event Log");

  // Ensure the sheet has headers.
  if (sheet.getLastRow() === 0) {
    sheet.appendRow(["Event ID", "Title", "Start Time", "End Time", "Calendar ID"]);
  }

  // Extract event details.
  const eventId: string = e.id;
  const title: string = e.title;
  const startTime: Date = new Date(e.startTime);
  const endTime: Date = new Date(e.endTime);
  const calendarId: string = e.calendarId;

  // Append the event details to the sheet.
  sheet.appendRow([eventId, title, startTime, endTime, calendarId]);
}

Эта функция принимает объект события (e) в качестве аргумента и извлекает из него нужную информацию, которую затем записывает в таблицу Google Sheets.

Ручное создание триггера с помощью редактора Apps Script

1. Откройте редактор Apps Script.
2. Перейдите в раздел «Триггеры» (значок часов).
3. Нажмите «Добавить триггер».
4. Настройте триггер:
   • Выберите функцию logCalendarEvent.
   • Выберите «Из календаря».
   • Выберите тип события (например, «При создании события»).
   • Выберите «Немедленно».
5. Сохраните триггер.

Создание триггера программно с использованием Script Service

Триггер можно создать программно, используя ScriptApp.newTrigger():

/**
 * Creates a calendar event trigger programmatically.
 */
function createCalendarEventTrigger(): void {
  // The function to run when the trigger fires.
  const functionName: string = "logCalendarEvent";

  // Create the trigger.
  ScriptApp.newTrigger(functionName)
    .forCalendar(CalendarApp.getDefaultCalendar().getId())
    .onEventUpdated() // Or .onEventCreated() or .onEventDeleted()
    .create();

  Logger.log("Calendar event trigger created.");
}

Этот код создаст триггер, который будет запускать функцию logCalendarEvent при каждом обновлении события в вашем основном календаре. Запустите эту функцию один раз, чтобы создать триггер.

Настройка параметров триггера для Календаря

Выбор типа событий для активации триггера (создание, изменение, удаление)

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

Определение конкретного календаря для триггера

Триггер можно привязать к определенному календарю. Это полезно, если у вас есть несколько календарей и вам нужно, чтобы триггер реагировал только на события в определенном из них. При программном создании используйте forCalendar(calendarId), где calendarId – идентификатор нужного календаря.

Установка временных ограничений (если необходимо)

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

Управление триггерами Календаря

Просмотр активных триггеров

Чтобы просмотреть все активные триггеры, откройте редактор Apps Script, перейдите в раздел «Триггеры» (значок часов). Здесь вы увидите список всех триггеров, связанных с вашим скриптом.

Редактирование существующих триггеров

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

Удаление триггеров, которые больше не нужны

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

Примеры использования триггеров Календаря

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

При создании нового события в календаре автоматически отправлять email-уведомления участникам:

/**
 * Sends an email notification when a new calendar event is created.
 * @param {GoogleAppsScript.Events.CalendarEvent} e The event object passed to the trigger.
 */
function sendEventNotification(e: GoogleAppsScript.Events.CalendarEvent): void {
  const eventTitle: string = e.title;
  const startTime: Date = new Date(e.startTime);
  const endTime: Date = new Date(e.endTime);
  const calendarId: string = e.calendarId;
  const event = CalendarApp.getCalendarById(calendarId).getEventById(e.id);
  const guests = event.getGuests();

  const subject: string = `New Calendar Event: ${eventTitle}`;
  const body: string = `A new event has been created:\nTitle: ${eventTitle}\nStart Time: ${startTime}\nEnd Time: ${endTime}`;

  // Send email to guests.
  if(guests) {
    guests.split(",").forEach(guest => {
      MailApp.sendEmail(guest, subject, body);
    });
  }

  Logger.log("Notification sent for event: " + eventTitle);
}

Создайте триггер типа On event creation и привяжите его к этой функции.

Синхронизация данных Календаря с другими системами

При изменении события в календаре можно автоматически обновлять информацию в CRM или другой системе учета. Это требует интеграции с API этих систем, что обычно реализуется через UrlFetchApp.

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

Например, при создании события с определенным названием (например, «Совещание») автоматически создавать задачу в Google Tasks или другом таск-менеджере. Это похоже на пример с CRM, но вместо обновления данных, создается новая задача. Можно использовать API Google Tasks или сторонние API для других сервисов.