Триггеры: расписание и события

Триггер запускает функцию скрипта без участия человека: по расписанию или в ответ на событие. Триггеры настраиваются на вкладке «Триггеры» редактора скрипта кнопкой «Добавить триггер».

Виды триггеров

Триггер	Когда срабатывает	Функция получает
По расписанию	каждые 15 или 30 минут, каждые 1, 2, 3, 4, 6, 8 или 12 часов, раз в день в заданное время, раз в неделю в заданный день и время	ничего
При изменении	после правки ячеек в таблице, можно ограничить листом и диапазоном	изменённые ячейки
При отправке формы	после каждого ответа на форму, связанную с таблицей	ответы формы
При открытии	когда таблицу открывает участник с правом редактирования, не чаще раза в 10 минут	кто и когда открыл
По вебхуку	при запросе на секретный адрес из внешнего сервиса	тело, параметры и заголовки запроса

В карточке созданного триггера эти виды называются полностью: «При изменении таблицы», «При открытии таблицы». У одного скрипта может быть до 5 триггеров. Триггер можно выключить и включить переключателем, не удаляя его. Время расписания считается по часовому поясу из вашего профиля, он указан под настройками расписания.

По расписанию

function main() {
  const sheet = Coverse.table.getSheet("Заказы");
  const count = sheet.getLastRow() - 1;
  Telegram.send(123456789, "Заказов в таблице: " + count);
}

Если предыдущий запуск ещё не закончился, очередной запуск по расписанию пропускается. В карточке триггера видно время следующего запуска, статус последнего и число запусков и ошибок за сегодня.

При изменении таблицы

function onEdit(event) {
  if (!event) return;

  for (const change of event.changes) {
    if (change.sheet === "Заказы" && change.column === 5 && change.value === "Оплачен") {
      Coverse.table.getSheet("Заказы").getRange(change.row, 1, 1, 7).setBackground("#d9ead3");
    }
  }
}

Поля события:

Поле	Что содержит
event.changes	изменённые ячейки: sheet, cell (например "E5"), row, column, value, displayValue, formula
event.authors	кто внёс изменения: id, name
event.source	откуда правка: "user" (в таблице), "api" (через API), "mixed"
event.sheet, event.range, event.value	лист, адрес и значение первой изменённой ячейки
event.cellCount	сколько ячеек изменилось всего
event.truncated	true, если ячеек больше, чем пришло в changes, или длинные значения обрезаны

Особенности:

• Правки за несколько секунд собираются в одно событие, поэтому вставка большого блока не запускает скрипт на каждую ячейку.
• В changes приходит до 200 ячеек. Если изменилось больше, truncated равно true: прочитайте нужный диапазон сами.
• Изменения, которые делают скрипты, триггер не запускают. Скрипт, который пишет в таблицу при изменении, не уйдёт в бесконечный цикл.
• В настройках триггера можно указать лист и диапазон, например C2:C100 или A:D. Правки вне диапазона скрипт не запустят.
• Если скрипт ещё работает, новые правки дождутся окончания запуска и придут следующим событием.
• В value дата приходит объектом Date, число числом, остальное текстом.

При отправке формы

function onFormSubmit(event) {
  if (!event) return;

  const name = event.namedValues["Имя"][0];
  const phone = event.namedValues["Телефон"][0];
  Telegram.send(123456789, "Новая заявка: " + name + ", " + phone);
}

Поле	Что содержит
event.answers	ответы: question, answer
event.namedValues	ответы по тексту вопроса, у каждого вопроса массив: event.namedValues["Имя"][0]
event.values	ответы списком в порядке вопросов
event.form	id и title формы
event.sheet, event.row	лист и строка, куда записан ответ
event.submittedAt	время отправки
event.respondent	кто отправил, если ответ дал вошедший пользователь, иначе null

Если ответы приходят быстрее, чем скрипт успевает их обработать, они встают в очередь и обрабатываются по порядку. В очереди ждёт до 50 ответов, следующие пропускаются.

При открытии таблицы

function onOpen(event) {
  if (!event) return;
  Coverse.table.getSheet("Сводка").getRange("B1").setValue(new Date());
}

Скрипт запускается в фоне после того, как таблица открылась, и не задерживает её загрузку. На одну таблицу — не чаще раза в 10 минут. event.openedAt содержит время открытия, event.authors — того, кто открыл. Триггер подходит для обновления данных, но не для приветствия каждого посетителя или подсчёта визитов.

По вебхуку

Внешний сервис отправляет запрос на секретный адрес, скрипт получает тело запроса. Настройка адреса, защита и примеры — в статье Вебхуки.

Проверка с тестовым событием

Функцию для триггера удобно проверить до того, как событие случится. В меню рядом с кнопкой «Запустить» выберите «Запустить с событием»:

• Тестовое событие — изменение одной ячейки на активном листе, ответ тестовой формы, тестовый запрос с заказом в JSON или открытие таблицы вами;
• Последнее из журнала — настоящее событие, с которым скрипт запускался раньше.

Без события функция получит event, равный undefined, поэтому в примерах выше первая строка if (!event) return;.

Уведомления об ошибках

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

Когда триггер не срабатывает

• Закончились минуты на сегодня: запуски по расписанию пропускаются до начала следующих суток по часовому поясу владельца.
• Тариф владельца больше не включает скрипты.
• Владелец скрипта или создатель триггера потерял право редактировать таблицу: триггер выключается и показывает причину.
• У владельца уже выполняется несколько скриптов: запуск по расписанию пропускается, события ждут свободного места.

Статус последнего запуска и причина пропуска видны в карточке триггера. Подробнее в статьях Лимиты и Права и безопасность.