Al igual que los activadores simples, los activadores instalables permiten que Apps Script ejecute una función automáticamente cuando se produce un evento determinado, como abrir un documento. Sin embargo, los activadores instalables ofrecen más más flexibles que los activadores simples: pueden llamar servicios que requieren autorización, ofrecen varios tipos adicionales de eventos, incluidos los basados en el tiempo (reloj), y pueden controlarse de manera programática. Tanto para las tareas instalables, Apps Script pasa la función activada un objeto de evento que contiene información sobre el contexto en el que ocurrió el evento.
Restricciones
Aunque los activadores instalables ofrecen más flexibilidad que los activadores simples, están sujetos a varias restricciones:
- No se ejecutan si un archivo se abre en modo de solo lectura (ver o comentar). Para independientes, los usuarios necesitan, al menos, acceso de lectura al archivo de secuencia de comandos en para que los activadores se ejecuten correctamente.
Las ejecuciones de secuencias de comandos y las solicitudes a la API no provocan la ejecución de activadores. Por ejemplo: llamando
FormResponse.submit()enviar una nueva respuesta de formulario no provoca la ejecución del activador de envío del formulario.Los activadores instalables siempre se ejecutan en la cuenta de la persona que los creó de ellos. Por ejemplo, si creas un activador abierto instalable, este se ejecuta Cuando tu colega abra el documento (si tiene acceso de edición) pero se ejecuta como tu cuenta. Esto significa que, si creas un activador para enviar un correo electrónico cuando se abre un documento, el correo electrónico siempre se envía desde tu cuenta, no necesariamente desde la cuenta que abrió el documento. Sin embargo, puedes crear un activador instalable para cada cuenta, lo que generaría un correo electrónico enviado desde cada cuenta.
Una cuenta determinada no puede ver los activadores instalados desde otra cuenta, incluso aunque la primera cuenta aún puede activar esos activadores.
Los activadores instalables están sujetos al activador de Apps Script límites de cuota.
Activadores basados en el tiempo
Un activador controlado por el tiempo (también llamado activador de reloj) es similar a un trabajo cron en Unix. Los activadores basados en el tiempo se ejecutan a una hora particular o en un intervalo recurrente, con tanta frecuencia como cada minuto o con una frecuencia menor, una vez al mes. (Ten en cuenta que un complemento puedes usar un activador controlado por el tiempo una vez por hora como máximo). El tiempo puede ser ligeramente aleatorias, por ejemplo, si crea un activador recurrente a las 9 a.m., Apps Script elige una hora entre las 9 a.m. y las 10 a.m., luego ese horario coherente de un día a otro, de modo que puedan pasar 24 horas se activa de nuevo el activador.
El siguiente es un ejemplo de un App de Google Chat que publique un mensaje cada minuto en cada espacio en el que se encuentre la app:
// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
// https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.
// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
PropertiesService.getScriptProperties()
.setProperty(e.space.name, '');
return {
'text': 'Hi! I\'ll post a message here every minute. ' +
'Please remove me after testing or I\'ll keep spamming you!'
};
}
// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
PropertiesService.getScriptProperties()
.deleteProperty(e.space.name);
}
// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
var spaceIds = PropertiesService.getScriptProperties()
.getKeys();
var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
for (var i = 0; i < spaceIds.length; ++i) {
postMessage(spaceIds[i], message);
}
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';
// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
var service = OAuth2.createService('chat')
.setTokenUrl('https://accounts.google.com/o/oauth2/token')
.setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
.setClientId(SERVICE_ACCOUNT_EMAIL)
.setPropertyStore(PropertiesService.getUserProperties())
.setScope(SCOPE);
if (!service.hasAccess()) {
Logger.log('Authentication error: %s', service.getLastError());
return;
}
var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
UrlFetchApp.fetch(url, {
method: 'post',
headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
contentType: 'application/json',
payload: JSON.stringify(message),
});
}
Activadores basados en eventos
Los activadores basados en eventos instalables son conceptualmente similares a
activadores simples
como onOpen(), pero pueden responder a eventos adicionales y se comportan
de forma diferente.
Por ejemplo, el activador de apertura instalable para Hojas de cálculo de Google
se activa cada vez que un usuario con acceso de edición abre la hoja de cálculo,
de la misma manera que el activador onOpen() simple. Sin embargo, la versión instalable
llamar a servicios que requieren
autorización. La versión instalable se ejecuta con la autorización del usuario que creó el activador, incluso si otro usuario con acceso de edición abre la hoja de cálculo.
Existen varios activadores instalables Google Workspace aplicaciones:
- Un activador open instalable se ejecuta cuando un usuario abre una hoja de cálculo. documento o formulario para el que tiene permiso para editar.
- Un activador edit instalable se ejecuta cuando un usuario modifica un valor en una en una hoja de cálculo.
- Un activador de cambio instalable se ejecuta cuando un usuario modifica la estructura de una hoja de cálculo propiamente dicha, por ejemplo, agregando una hoja nueva o quitando .
- Un activador de envío de formulario instalable se ejecuta cuando un usuario responde a un formulario. Existen dos versiones del activador de envío de formulario: una para Formularios de Google y uno para Hojas de cálculo si el formulario se envía a una hoja de cálculo.
- Un activador de evento de calendario instalable se ejecuta cuando los eventos de calendario de un usuario se actualicen, creen, editen o borren.
Puedes usar activadores instalables en secuencias de comandos independientes y vinculadas. Por ejemplo:
una secuencia de comandos independiente puede crear de manera programática un activador instalable para un
archivo arbitrario de Hojas de cálculo de Google llamando
TriggerBuilder.forSpreadsheet(key)
y pasar el ID de la hoja de cálculo.
Administra activadores de forma manual
Para crear manualmente un activador instalable en el editor de secuencia de comandos, sigue estos pasos: sigue estos pasos:
- Abre tu proyecto de Apps Script.
- A la izquierda, haz clic en Activadores .
- En la esquina inferior derecha, haz clic en Agregar activador.
- Selecciona y configura el tipo de activador que deseas crear.
- Haz clic en Guardar.
Administra activadores de forma programática
También puedes crear y borrar activadores de manera programática con el
Servicio de secuencia de comandos. Comienza llamando a ScriptApp.newTrigger(functionName), que muestra un TriggerBuilder.
En el siguiente ejemplo, se muestra cómo crear dos activadores basados en el tiempo: uno que se activa cada 6 horas y otro que se activa todos los lunes a las 9 a.m. (en la zona horaria en la que se configuró la secuencia de comandos).
En el siguiente ejemplo, se muestra cómo crear un activador abierto instalable para un
en una hoja de cálculo. Ten en cuenta que, a diferencia de un activador onOpen() simple, la secuencia de comandos del activador instalable no necesita estar vinculada a la hoja de cálculo. Para crear
este activador desde una secuencia de comandos independiente, solo debes reemplazar
SpreadsheetApp.getActive() con una llamada a
SpreadsheetApp.openById(id)
Para modificar de forma programática un activador instalable existente, debes borrarlo y crear uno nuevo. Si ya almacenaste el ID de un activador, puedes y borrarlo. Para ello, pasa el ID como argumento a la siguiente función.
Errores en activadores
Cuando se activa un activador instalable, pero la función arroja una excepción o de lo contrario, no se ejecutará correctamente, no verás un mensaje de error en tu en la pantalla. Después de todo, cuando se ejecuta un activador controlado por el tiempo o cuando otro usuario activa con el activador del envío de formularios, es posible que ni siquiera esté en la computadora.
En cambio, Apps Script te envía un correo electrónico como el siguiente:
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.
El correo electrónico incluye un vínculo para desactivar o volver a configurar el activador. Si el botón de la secuencia de comandos vinculado a Hojas de cálculo, Documentos o Formularios de Google el correo electrónico también incluye un vínculo a ese archivo. Estos vínculos te permiten desactiva el activador o edita la secuencia de comandos para corregir el error.
Para revisar todos los activadores asociados con tu Cuenta de Google desactiva los activadores que ya no necesitas, sigue estos pasos:
- Ve a
script.google.com. - A la izquierda, haz clic en Mis activadores.
Para borrar un activador, a la derecha del activador, haz clic en Más Borrar activador.
Activadores en complementos
Además de los activadores instalables, puedes usar activadores de manifiestos en los complementos. Para obtener más información, ver Activadores para los complementos de Google Workspace.