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

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

Ограничения

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

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

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

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

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

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

Триггеры, срабатывающие по времени

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

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

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

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

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

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

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

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

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

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

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

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

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

triggers/triggers.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) .

triggers/triggers.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();
}

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

triggers/triggers.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, в письме также содержится ссылка на этот файл. Эти ссылки позволяют деактивировать триггер или отредактировать скрипт для исправления ошибки.

To troubleshoot errors in your script, click the link in the notification email to open your script project. Once the project is open, view the execution logs by clicking Executions in the left navigation panel. The logs show which executions failed and include error messages to help you diagnose and fix the problem.

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

  1. Перейдите на script.google.com .
  2. Слева нажмите «Мои триггеры» .
  3. Чтобы удалить триггер, справа от триггера нажмите > «Удалить триггер» .

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

 Note: Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, you must edit the appropriate script and remove or rename
 the `onOpen()` function.

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

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