Триггеры позволяют Apps Script автоматически запускать функцию при возникновении определенного события, например открытия документа. Простые триггеры — это набор зарезервированных функций, встроенных в Apps Script, например функция onOpen(e)
, которая выполняется, когда пользователь открывает файл Google Docs, Sheets, Slides или Forms. Устанавливаемые триггеры предлагают больше возможностей, чем простые триггеры, но их необходимо активировать перед использованием. Для обоих типов триггеров Apps Script передает триггерной функции объект события , содержащий информацию о контексте, в котором произошло событие.
Начиная
Чтобы использовать простой триггер, просто создайте функцию, которая использует одно из этих зарезервированных имен функций:
-
onOpen(e)
запускается, когда пользователь открывает электронную таблицу, документ, презентацию или форму, на редактирование которых у него есть разрешение. -
onInstall(e)
запускается, когда пользователь устанавливает надстройку редактора из Документов, Таблиц, Слайдов или Форм Google. -
onEdit(e)
запускается, когда пользователь меняет значение в электронной таблице. -
onSelectionChange(e)
запускается, когда пользователь меняет выбор в электронной таблице. -
doGet(e)
запускается, когда пользователь посещает веб-приложение или программа отправляет HTTP-запросGET
в веб-приложение. -
doPost(e)
запускается, когда программа отправляет запрос HTTPPOST
в веб-приложение.
Параметр e
в именах функций выше — это объект события , который передается функции. Объект содержит информацию о контексте, вызвавшем срабатывание триггера, но его использование не является обязательным.
Ограничения
Поскольку простые триггеры срабатывают автоматически, без запроса авторизации пользователя, на них распространяется ряд ограничений:
- Сценарий должен быть привязан к файлу Google Sheets, Slides, Docs или Forms или быть надстройкой , расширяющей одно из этих приложений.
- Они не запускаются, если файл открыт в режиме только для чтения (просмотр или комментарий).
- Выполнение сценариев и запросы API не вызывают запуск триггеров. Например, вызов
Range.setValue()
для редактирования ячейки не приводит к запуску триггераonEdit
электронной таблицы. - Они не могут получить доступ к службам , требующим авторизации . Например, простой триггер не может отправить электронное письмо, поскольку служба Gmail требует авторизации, но простой триггер может перевести фразу с помощью языковой службы , которая является анонимной.
- Они могут изменять файл, к которому привязаны, но не могут получить доступ к другим файлам, поскольку для этого потребуется авторизация.
- Они могут или не могут определить личность текущего пользователя, в зависимости от сложного набора ограничений безопасности .
- Они не могут бежать дольше 30 секунд.
- В определенных обстоятельствах надстройки редактора запускают простые триггеры
onOpen(e)
иonEdit(e)
в режиме без авторизации, что создает некоторые дополнительные сложности. Дополнительные сведения см. в руководстве по жизненному циклу авторизации надстройки . - На простые триггеры распространяются ограничения квоты триггеров Apps Script.
Эти ограничения не применяются к doGet(e)
или doPost(e)
.
onOpen(e)
Триггер onOpen(e)
запускается автоматически, когда пользователь открывает электронную таблицу, документ, презентацию или форму, на редактирование которых у него есть разрешение. (Триггер не срабатывает при ответе на форму, а только при открытии формы для ее редактирования.) onOpen(e)
чаще всего используется для добавления пользовательских элементов меню в Google Sheets, Slides, Docs или Forms.
onInstall(e)
Триггер onInstall(e)
срабатывает автоматически, когда пользователь устанавливает надстройку редактора из Документов, Таблиц, Слайдов или Форм Google. Триггер не сработает, когда пользователь установит надстройку с веб-сайта Google Workspace Marketplace . Обратите внимание, что существуют определенные ограничения на действия onInstall(e)
. Узнайте больше об авторизации . Наиболее распространенное использование onInstall(e)
— это простой вызов onOpen(e)
для добавления пользовательских меню. В конце концов, когда надстройка установлена, файл уже открыт, и, следовательно, onOpen(e)
не запускается сам по себе, пока файл не будет открыт повторно.
onEdit(e)
Триггер onEdit(e)
запускается автоматически, когда пользователь меняет значение любой ячейки в электронной таблице. Большинство триггеров onEdit(e)
используют информацию в объекте события для соответствующего реагирования. Например, функция onEdit(e)
ниже устанавливает комментарий к ячейке, в котором записан последний раз ее редактирование.
onSelectionChange(e)
Триггер onSelectionChange(e)
запускается автоматически, когда пользователь меняет выбор в электронной таблице. Чтобы активировать этот триггер, необходимо обновлять электронную таблицу после добавления триггера и каждый раз при открытии таблицы.
Если выделение перемещается между несколькими ячейками за короткое время, некоторые события изменения выделения могут быть пропущены, чтобы уменьшить задержку. Например, если много изменений выбора производится с разницей в две секунды, только первое и последнее изменения выбора активируют триггер onSelectionChange(e)
.
В приведенном ниже примере, если выбрана пустая ячейка, функция onSelectionChange(e)
устанавливает красный фон ячейки.
doGet(e)
и doPost(e)
Триггер doGet(e)
запускается автоматически, когда пользователь посещает веб-приложение или когда программа отправляет HTTP-запрос GET
в веб-приложение. doPost(e)
запускается, когда программа отправляет запрос HTTP POST
в веб-приложение. Эти триггеры подробно описаны в руководствах по веб-приложениям , службе HTML и службе контента . Обратите внимание, что doGet(e)
и doPost(e)
не подпадают под ограничения, перечисленные выше.
Доступные типы триггеров
Если ограничения на простые триггеры не позволяют им удовлетворить ваши потребности, вместо них может подойти устанавливаемый триггер . В таблице ниже приведены типы триггеров, доступные для каждого типа событий. Например, Google Sheets, Slides, Forms и Docs поддерживают простые триггеры открытия, но только Таблицы, Документы и Формы поддерживают устанавливаемые триггеры открытия.
Событие | Простые триггеры | Устанавливаемые триггеры |
---|---|---|
Открыть | ![]() ![]() ![]() ![]() | ![]() ![]() ![]() |
Редактировать | ![]() | ![]() |
Изменение выбора | ![]() | |
Установить | ![]() ![]() ![]() ![]() | |
Изменять | ![]() | |
Отправка формы | ![]() ![]() | |
Управляемый временем (часы) | ![]() ![]() ![]() ![]() ![]() | |
Получать | ![]() | |
Почта | ![]() |
* Событие открытия для Google Forms происходит не тогда, когда пользователь открывает форму для ответа, а когда редактор открывает форму, чтобы изменить ее.