Activadores instalables

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

Nota: Para obtener información sobre cómo usar activadores instalables en proyectos de complementos, consulta Activadores de complementos.

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 está abierto en modo de solo lectura (ver o comentar). En el caso de las secuencias de comandos independientes, los usuarios necesitan, al menos, acceso de lectura 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 a FormResponse.submit() para enviar una respuesta de formulario nueva no hace que se ejecute el activador de envío del formulario.

  Nota: 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 las calificaciones ya existen 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 abierto instalable, este se ejecuta cuando tu colega abre el documento (si tu colega 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 siempre se envía desde tu cuenta, no necesariamente la cuenta que abrió el documento. Sin embargo, puedes crear un activador instalable para cada cuenta, lo que daría como resultado 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 pueda activar esos activadores.

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

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 permiten que las secuencias de comandos se ejecuten en un momento determinado o en un intervalo recurrente, con una frecuencia de un minuto o una vez por mes. (Ten en cuenta que un complemento puede usar un activador controlado por 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 un horario entre las 9 a.m. y las 10 a.m., y luego mantiene ese horario coherente de un día a otro para que transcurran 24 horas antes de que se active de nuevo el activador.

Activadores basados en eventos

Desde una perspectiva conceptual, los activadores controlados por eventos instalables son similares a los activadores simples, como onOpen(), pero pueden responder a eventos adicionales y se comportan de manera diferente.

Por ejemplo, el activador abierto instalable para Hojas de cálculo de Google se activa cada vez que un usuario que tiene acceso de edición abre la hoja de cálculo, al igual que el activador onOpen() simple. Sin embargo, la versión instalable puede llamar a servicios que requieran 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.

Hay varios activadores instalables para las Google Workspace aplicaciones:

• Un activador open instalable se ejecuta cuando un usuario abre una hoja de cálculo, un documento o un formulario para el cual tiene permiso de edición.
• Un activador edit 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, cuando agrega una hoja nueva o quita una columna.
• Cuando un usuario responde un formulario, se ejecuta un activador instalable de envío de formulario. Existen dos versiones del activador de envío de formulario: una para los Formularios de Google y otra para las 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 actualizan, crean, editan o borran.

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 a TriggerBuilder.forSpreadsheet(key) y pasando el ID de la hoja de cálculo.

Administra activadores de forma manual

Para crear un activador instalable de forma manual 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 parte 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 manera programática

También puedes crear y borrar activadores de manera programática con el servicio de secuencia de comandos. Comienza por llamar 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).

desencadenadores/triggers.gs

Ver en GitHub

/**
 * 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 abierto instalable para 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() por una llamada a SpreadsheetApp.openById(id).

desencadenadores/triggers.gs

Ver en GitHub

/**
 * 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 manera programática un activador instalable existente, debes borrarlo y crear uno nuevo. Si ya almacenaste el ID de un activador, puedes borrarlo si pasas el ID como un argumento a la siguiente función.

desencadenadores/triggers.gs

Ver en GitHub

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

Errores en los activadores

Cuando se activa un activador instalable, pero la función muestra una excepción o no se ejecuta de otro modo correctamente, no verás un mensaje de error en la pantalla. Después de todo, cuando un activador controlado por el tiempo o algún otro usuario activa el activador de envío de formulario, es posible que ni siquiera estés en la computadora.

En su lugar, Apps Script le enviará un correo electrónico como el siguiente:

From: [e-mail]
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 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 incluirá un vínculo a ese archivo. Estos vínculos te permiten desactivar el activador o editar la secuencia de comandos para corregir el error.

Nota: 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 activadores 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.

   Nota: Los activadores simples, como onOpen(), no se pueden desactivar desde esta página; en su lugar, debes editar la secuencia de comandos adecuada y quitar o cambiar el nombre de la función onOpen().

Activadores instalables en complementos

Para obtener más información sobre el uso de activadores instalables en complementos, consulta Activadores de complementos.