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

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

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

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

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

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

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

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

Событие Объект события Простые триггеры Устанавливаемые триггеры
Открыть
Открывается файл редактора.		 Документация по объекту события Open
Объект события Forms onOpen
Объект события Sheets onOpen
Объект события Slides onOpen 		Документы
Формы*
Листы
Слайды

function onOpen(e)

 Документы
Формы
Листы
Установить
Дополнение установлено.		 объект события onInstall Документы
Формы
Листы
Слайды

function onInstall(e)

Редактировать
Содержимое ячейки электронной таблицы изменено.		 Объект события Sheets onEdit Листы

function onEdit(e)

 Листы
Изменять
Содержимое листа редактируется или форматируется.		 Объект события Sheets onChange Листы
Форма-отправить
Отправляется Google-форма.		 Объект события отправки формы Forms
Объект события отправки формы Таблиц 		Формы
Листы
Управляемый временем (часы)
Триггер срабатывает в указанное время или с заданным интервалом.		 Объект события, управляемого временем Документы
Формы
Листы
Слайды

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

Простые триггеры в дополнениях

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

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

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

Ограничения

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

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

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

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

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

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

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

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

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

Разрешение на установку триггеров

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

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

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

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

Код.gs

триггеры/форма/Код.gs
/**
 * 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.
  }
}

авторизацияemail.html

triggers/form/AuthorizationEmail.html
<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 или неопубликованная надстройка вообще не выполняется, если какая-либо часть скрипта требует авторизации.
  • Устанавливаемые триггеры подпадают под ограничения квоты триггеров Apps Script.