Activadores instalables

Al igual que los activadores simples, los activadores instalables permiten que Google 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 flexibilidad que los activadores simples: pueden llamar a servicios que requieren autorización, ofrecen varios tipos de eventos adicionales, incluidos los activadores basados en el tiempo (reloj), y se pueden controlar de forma programática. Tanto para los activadores simples como para los instalables, Apps Script pasa a la función activada un objeto de evento que contiene información sobre el contexto en el que se produjo el evento.

Para obtener más información sobre cómo usar activadores en complementos, consulta Activadores para complementos de Google Workspace.

Restricciones

Aunque los activadores instalables ofrecen más flexibilidad que los activadores simples, aún están sujetos a varias restricciones:

  • No se ejecutan si un archivo se abre en modo de solo lectura (ver o comentar). En el caso de las secuencias de comandos independientes, los usuarios necesitan al menos acceso de visualización al archivo de secuencia de comandos para que los activadores se ejecuten correctamente.

  • Las ejecuciones de secuencias de comandos y las solicitudes a la API no hacen que se ejecuten los activadores. Por ejemplo, llamar FormResponse.submit() para enviar una respuesta de formulario nueva no hace que se ejecute el activador de envío del formulario.

    Una excepción a esta restricción es Form.submitGrades(). Si tu código usa un activador onFormSubmit, llamar a Form.submitGrades() activa la condición onFormSubmit y provoca un bucle infinito. Para evitar el bucle infinito, agrega código que verifique si ya existen calificaciones antes de llamar a submitGrades().

  • Los activadores instalables siempre se ejecutan en la cuenta de la persona que los creó. Por ejemplo, si creas un activador de apertura instalable, se ejecuta cuando tu colega abre 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 genera un correo electrónico enviado desde cada cuenta.

  • Una cuenta determinada no puede ver los activadores instalados desde una segunda cuenta, aunque la primera cuenta aún puede activar esos activadores.

  • Los activadores instalables están sujetos a los límites de cuota de activadores de Apps Script .

Activadores basados en el tiempo

Un activador basado en el tiempo (también llamado activador de reloj) es similar a un trabajo cron en Unix. Los activadores basados en el tiempo permiten que las secuencias de comandos se ejecuten en un momento determinado o en un intervalo recurrente, con una frecuencia de cada minuto o una vez al mes. (Un complemento puede usar un activador basado en el tiempo una vez por hora como máximo). La hora puede ser un poco aleatoria. Por ejemplo, si creas un activador recurrente a las 9 a.m., Apps Script elige una hora entre las 9 a.m. y las 10 a.m. y, luego, mantiene esa sincronización de un día para otro para que transcurran 24 horas antes de que se vuelva a activar el activador.

Activadores basados en eventos

Los activadores instalables basados en eventos son conceptualmente similares a activadores simples como onOpen(), pero pueden responder a eventos adicionales y se comportan de manera diferente.

Por ejemplo, el activador de apertura instalable para Hojas de cálculo de Google se activa cada vez que cualquier usuario que tenga acceso de edición abre la hoja de cálculo, al igual que el activador simple onOpen(). Sin embargo, la versión instalable puede 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 para las aplicaciones de Google Workspace:

  • Un activador de apertura instalable se ejecuta cuando un usuario abre una hoja de cálculo, un documento o un formulario que tiene permiso para editar.
  • Un activador de edición instalable se ejecuta cuando un usuario modifica un valor 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, por ejemplo, agregando una hoja nueva o quitando una columna.
  • 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 otra 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 se actualizan los eventos del calendario de un usuario (se crean, editan o borran).

Los activadores instalables están disponibles en secuencias de comandos independientes y vinculadas. Por ejemplo, una secuencia de comandos independiente puede crear de forma programática un activador instalable para un archivo arbitrario de Hojas de cálculo de Google llamando a TriggerBuilder.forSpreadsheet(key) y pasando el ID de la hoja de cálculo.

Administra activadores de forma manual

Para crear manualmente un activador instalable en el editor de secuencias de comandos, sigue estos pasos:

  1. Abre tu proyecto de Apps Script.
  2. A la izquierda, haz clic en Activadores .
  3. En la esquina inferior derecha, haz clic en Agregar activador.
  4. Selecciona y configura el tipo de activador que deseas crear.
  5. Haz clic en Guardar.

Administra activadores de forma programática

Crea y borra activadores de forma programática con el servicio Script. Para comenzar, llama 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 está configurada tu secuencia de comandos).

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

En el siguiente ejemplo, se muestra cómo crear un activador de apertura instalable para una hoja de cálculo. A diferencia de un activador onOpen() simple, la secuencia de comandos para el activador instalable no necesita estar vinculada a la hoja de cálculo. Para crear este activador a partir de una secuencia de comandos independiente, reemplaza SpreadsheetApp.getActive() por una llamada a 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();
}

Para modificar de forma programática un activador instalable existente, debes borrarlo y crear uno nuevo. Si almacenaste previamente el ID de un activador, bórralo pasando el ID como argumento a la siguiente función.

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;
    }
  }
}

Antes de crear un activador, verifica que la función asociada tenga todos los permisos de OAuth necesarios.

Errores en los activadores

Cuando se activa un activador instalable, pero la función arroja una excepción o no se ejecuta correctamente, no aparece ningún mensaje de error en la pantalla. Después de todo, cuando se ejecuta un activador basado en el tiempo o cuando otro usuario activa el activador de envío de formulario, es posible que ni siquiera estés en tu computadora.

En su lugar, Apps Script envía un correo electrónico como el siguiente:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for 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 la secuencia de comandos está vinculada a un archivo de 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 desactivar el activador o editar la secuencia de comandos para corregir el error.

Para solucionar problemas de errores en tu secuencia de comandos, haz clic en el vínculo del correo electrónico de notificación para abrir el proyecto de secuencia de comandos. Una vez que se abra el proyecto, haz clic en Ejecuciones en el panel de navegación izquierdo para ver los registros de ejecución. Los registros muestran qué ejecuciones fallaron e incluyen mensajes de error para ayudarte a diagnosticar y corregir el problema.

Los activadores instalables creados por complementos no envían a los usuarios estos avisos por correo electrónico.

Para revisar todos los activadores asociados con tu Cuenta de Google y desactivar los que ya no necesitas, sigue estos pasos:

  1. Ve a script.google.com.
  2. A la izquierda, haz clic en Mis activadores.
  3. Para borrar un activador, a la derecha del activador, haz clic en Más > Borrar activador.

Si se desactiva un activador, también se desactivan sus notificaciones de fallas correspondientes. Las notificaciones de fallas son una parte inherente de un activador activo. Por lo tanto, para dejar de recibir todas las notificaciones de fallas de un activador específico, desactiva o borra el activador. Mientras un activador esté activo, solo podrás ajustar la frecuencia de estas notificaciones.

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

Activadores en complementos

Además de los activadores instalables, usa activadores de manifiesto en complementos. Para obtener más información, consulta Activadores para complementos de Google Workspace.