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

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

Ограничения

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете использовать устанавливаемые триггеры в автономных и связанных скриптах. Например, автономный скрипт может программно создать устанавливаемый триггер для произвольного файла 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 .