Триггеры для надстроек редактора

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

При срабатывании триггера создается объект события . Эта структура JSON содержит сведения о произошедшем событии. Информация в структуре объекта события организована по-разному в зависимости от типа триггера.

После создания объекта события Apps Script передает его в качестве параметра функции триггера. Функция триггера — это функция обратного вызова, которую вы должны реализовать самостоятельно, чтобы предпринимать любые действия, подходящие для ответа на событие. Например, в надстройке редактора триггер используется для создания дополнительных пунктов меню при открытии документа. В этом случае вы реализуете триггерную функцию onOpen(e) для создания элементов меню, необходимых надстройке, возможно, используя данные в объекте события.

На этой странице представлены рекомендации по использованию триггеров в надстройках редактора.

Типы триггеров надстройки редактора

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

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

Событие	Объект события	Простые триггеры	Устанавливаемые триггеры
Открыть Открывается файл редактора.	Объект события Docs onOpen Формирует объект события onOpen Объект события Sheets onOpen Слайды на объекте события Open	Документы Формы* Листы Слайды function onOpen(e)	Документы Формы* Листы
Установить Дополнение установлено.	объект события onInstall	Документы Формы Листы Слайды function onInstall(e)
Редактировать Содержимое ячейки электронной таблицы изменено.	Объект события Sheets onEdit	Листы function onEdit(e)	Листы
Изменение Содержимое листа редактируется или форматируется.	Объект события Sheets onChange		Листы
Отправить форму Гугл-форма отправлена.	Forms объект события отправки формы Листы формируют объект события отправки		Формы Листы
Управляемый временем (часы) Триггер срабатывает в указанное время или интервал.	Объект события, управляемый временем		Документы Формы Листы Слайды

* Событие открытия для Google Forms происходит не тогда, когда пользователь открывает форму для ответа, а когда редактор открывает форму, чтобы изменить ее.

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

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

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

• onOpen(e) выполняется, когда пользователь открывает документ, электронную таблицу или презентацию. onOpen(e) также может выполняться при открытии формы в редакторе (но не при ответе на форму). Он выполняется только в том случае, если у пользователя есть разрешение на редактирование рассматриваемого файла, и чаще всего используется для создания пунктов меню .
• onInstall(e) выполняется, когда пользователь устанавливает надстройку. Обычно onInstall(e) просто используется для вызова onOpen(e) ; это гарантирует, что дополнительные меню появятся сразу после установки, не требуя от пользователя обновления страницы.
• onEdit(e) выполняется, когда пользователь изменяет значение ячейки в электронной таблице. Этот триггер не срабатывает в ответ на перемещение ячеек, форматирование или другие изменения, которые не изменяют значения ячеек.

Ограничения

На простые триггеры в надстройках распространяются те же ограничения , что и на простые триггеры в других типах проектов Apps Script. Обратите особое внимание на эти ограничения при разработке надстроек:

• Простые триггеры не запускаются, если файл открыт в режиме только для чтения (просмотр или комментарий). Это поведение предотвращает заполнение ваших дополнительных меню.
• В определенных обстоятельствах надстройки редактора запускают свои простые триггеры onOpen(e) и onEdit(e) в режиме без авторизации. Этот режим представляет некоторые дополнительные сложности, описанные в модели авторизации дополнений .
• Простые триггеры не могут использовать сервисы или выполнять другие действия, требующие авторизации , за исключением случаев, описанных в модели авторизации дополнений .
• Простые триггеры не могут работать дольше 30 секунд. Позаботьтесь о том, чтобы свести к минимуму объем обработки, выполняемой в простой триггерной функции.
• На простые триггеры распространяются квоты триггеров скриптов приложений.

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

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

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

Надстройки могут использовать следующие устанавливаемые триггеры:

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

• Устанавливаемые триггеры отправки формы выполняются при отправке ответа формы Google.

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

Авторизация устанавливаемых триггеров

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

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

В отличие от триггеров в обычных проектах Apps Script, триггеры в надстройках продолжают срабатывать, даже если им требуется повторная авторизация. Однако сценарий по-прежнему завершается ошибкой, если он сталкивается со строкой кода, требующей авторизации, которой у сценария нет. Чтобы избежать этой ситуации, разработчики могут использовать метод ScriptApp.getAuthorizationInfo() для ограничения доступа к частям кода, которые изменились между опубликованными версиями надстройки.

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

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Ограничения

На устанавливаемые триггеры в надстройках распространяются те же ограничения , что и на устанавливаемые триггеры в других типах проектов Apps Script.

В дополнение к этим ограничениям, к устанавливаемым триггерам в надстройках применяется несколько ограничений:

• Каждое дополнение может иметь только один триггер каждого типа для каждого пользователя и документа. Например, в данной электронной таблице у данного пользователя может быть только один триггер редактирования, хотя у пользователя также может быть триггер отправки формы или триггер времени в той же электронной таблице. У другого пользователя, имеющего доступ к той же электронной таблице, может быть свой собственный отдельный набор триггеров.
• Надстройки могут создавать триггеры только для файла, в котором используется надстройка. То есть надстройка, используемая в Google Doc A, не может создать триггер для отслеживания при открытии Google Doc B.
• Триггеры, управляемые временем, не могут запускаться чаще одного раза в час.
• Надстройки не отправляют пользователю электронное письмо автоматически, когда код, запускаемый устанавливаемым триггером, вызывает исключение. Разработчик должен корректно проверять и обрабатывать случаи сбоев.
• Дополнительные триггеры перестают срабатывать в любой из следующих ситуаций:
  • Если надстройка удалена пользователем,
  • Если надстройка отключена в документе (при ее повторном включении триггер снова становится работоспособным) или
  • Если разработчик отменяет публикацию надстройки или отправляет неработающую версию в магазин надстроек.
• Дополнительные триггерные функции выполняются до тех пор, пока не достигнут код, использующий неавторизованную службу, после чего они останавливаются. Это верно только в том случае, если надстройка опубликована; тот же триггер в обычном проекте Apps Script или неопубликованном дополнении вообще не выполняется, если какая-либо часть скрипта требует авторизации.
• На устанавливаемые триггеры распространяются квоты триггеров скриптов приложений.