Устанавливаемые триггеры

Как и простые триггеры , устанавливаемые триггеры позволяют Apps Script автоматически запускать функцию при наступлении определённого события, например, открытия документа. Однако устанавливаемые триггеры предлагают большую гибкость, чем простые: они могут вызывать службы , требующие авторизации , предлагают несколько дополнительных типов событий, включая триггеры, управляемые по времени (часам), и ими можно управлять программно. Как для простых, так и для устанавливаемых триггеров Apps Script передаёт вызываемой функции объект события , содержащий информацию о контексте, в котором произошло событие.

Ограничения

Несмотря на то, что устанавливаемые триггеры обеспечивают большую гибкость, чем простые триггеры, они все равно имеют ряд ограничений:

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

  • Выполнение скриптов и запросы API не приводят к срабатыванию триггеров. Например, вызов FormResponse.submit() для отправки нового ответа формы не приводит к срабатыванию триггера отправки формы.

  • Устанавливаемые триггеры всегда запускаются под учётной записью того пользователя, который их создал. Например, если вы создаёте устанавливаемый триггер открытия, он срабатывает, когда ваш коллега открывает документ (если у него есть права на редактирование), но запускается от имени вашей учётной записи. Это означает, что если вы создаёте триггер для отправки электронного письма при открытии документа, письмо всегда будет отправлено с вашей учётной записи, а не обязательно с той, которая открыла документ. Однако вы можете создать устанавливаемый триггер для каждой учётной записи, что приведёт к отправке одного электронного письма с каждой учётной записи.

  • Данная учетная запись не может видеть триггеры, установленные из второй учетной записи, даже если первая учетная запись по-прежнему может активировать эти триггеры.

  • Устанавливаемые триггеры подчиняются ограничениям квоты триггеров Apps Script.

Триггеры, управляемые временем

Триггер, управляемый временем (также называемый триггером часов), аналогичен заданию cron в Unix. Триггеры, управляемые временем, позволяют скриптам выполняться в определённое время или с повторяющимся интервалом, например, каждую минуту или не чаще, чем раз в месяц. (Обратите внимание, что надстройка может использовать триггер, управляемый временем, не чаще одного раза в час.) Время может быть слегка случайным — например, если вы создаёте повторяющийся триггер на 9 утра, Apps Script выбирает время между 9 и 10 утра, а затем поддерживает это время постоянным изо дня в день, чтобы до следующего срабатывания триггера прошло 24 часа.

Триггеры, управляемые событиями

Устанавливаемые событийно-управляемые триггеры концептуально похожи на простые триггеры , такие как onOpen() , но они могут реагировать на дополнительные события и ведут себя по-другому.

Например, устанавливаемый триггер открытия для Google Таблиц активируется при каждом открытии таблицы любым пользователем с правами на редактирование, как и простой триггер onOpen() . Однако устанавливаемая версия может вызывать службы , требующие авторизации . Устанавливаемая версия запускается с авторизацией пользователя, создавшего триггер, даже если другой пользователь с правами на редактирование открывает таблицу.

Существует несколько устанавливаемых триггеров дляGoogle Workspace приложения:

  • Устанавливаемый триггер открытия запускается, когда пользователь открывает электронную таблицу, документ или форму, на редактирование которых у него есть разрешение.
  • Устанавливаемый триггер редактирования срабатывает, когда пользователь изменяет значение в электронной таблице.
  • Устанавливаемый триггер изменений срабатывает, когда пользователь изменяет структуру самой электронной таблицы, например, добавляя новый лист или удаляя столбец.
  • Устанавливаемый триггер отправки формы срабатывает, когда пользователь заполняет форму. Существует две версии триггера отправки формы: одна для самих Google Форм, а другая для Таблиц, если форма отправляется в электронную таблицу .
  • Устанавливаемый триггер событий календаря срабатывает при обновлении событий календаря пользователя — их создании, редактировании или удалении.

Устанавливаемые триггеры можно использовать в автономных и связанных скриптах. Например, автономный скрипт может программно создать устанавливаемый триггер для произвольного файла Google Таблиц, вызвав TriggerBuilder.forSpreadsheet(key) и передав идентификатор таблицы.

Управляйте триггерами вручную

Чтобы вручную создать устанавливаемый триггер в редакторе скриптов, выполните следующие действия:

  1. Откройте проект Apps Script.
  2. Слева нажмите тревоги ».
  3. В правом нижнем углу нажмите «Добавить триггер» .
  4. Выберите и настройте тип триггера, который вы хотите создать.
  5. Нажмите «Сохранить» .

Программное управление триггерами

Вы также можете создавать и удалять триггеры программно с помощью сервиса Script . Начните с вызова ScriptApp.newTrigger(functionName) , который возвращает TriggerBuilder .

В следующем примере показано, как создать два триггера, управляемых по времени: один, который срабатывает каждые 6 часов, и один, который срабатывает каждый понедельник в 9 утра (в часовом поясе, на который настроен ваш скрипт).

триггеры/триггеры.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

В следующем примере показано, как создать устанавливаемый триггер открытия для электронной таблицы. Обратите внимание, что, в отличие от простого триггера onOpen() , скрипт устанавливаемого триггера не требуется привязывать к электронной таблице. Чтобы создать этот триггер из отдельного скрипта, просто замените SpreadsheetApp.getActive() вызовом SpreadsheetApp.openById(id) .

триггеры/триггеры.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

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

триггеры/триггеры.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Перед созданием триггера мы рекомендуем вам убедиться, что связанная с ним функция имеет все необходимые разрешения OAuth .

Ошибки в триггерах

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

Вместо этого Apps Script отправит вам электронное письмо следующего содержания:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

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

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

  1. Перейдите на script.google.com .
  2. Слева нажмите Мои триггеры .

  3. Чтобы удалить триггер, справа от триггера нажмите Дополнительно > Удалить триггер .

Триггеры в дополнениях

Помимо устанавливаемых триггеров, в дополнениях можно использовать манифестные триггеры. Подробнее см. в статье Триггеры для дополнений Google Workspace .