Autorización del complemento de editor

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En la mayoría de los casos, debes autorizar un complemento para poder usarlo. En muchos proyectos de Apps Script, como las apps web, la autorización es sencilla: el proyecto de secuencia de comandos solicita los permisos faltantes que necesita cuando intentas utilizarlos. Una vez autorizado, puedes usar el proyecto de secuencia de comandos con libertad. Todos los que usan el proyecto de secuencia de comandos lo autorizan por separado.

El modelo de autorización para los complementos de editor es más complejo. Debido a que estos complementos funcionan en archivos que residen en Google Drive (archivos que se pueden compartir con otros), debes compilar complementos de editor con los diferentes modos de autorización en mente. Las aplicaciones de editor de Google Workspace también proporcionan un menú de Complementos en sus IU que se propaga con los complementos que instalaste, incluso si aún no autorizaste esos complementos. Esto agrega complejidad al modelo de autorización.

Modelo de autorización

Dos propiedades de complementos de editor hacen que sea muy fácil compartirlos y usar lo siguiente:

  • Una vez que obtengas un complemento de editor de la tienda, lo verás en el menú Complementos de cada documento que abras o crees. Los colaboradores de esos documentos no verán el complemento, excepto en los documentos en los que realmente los use.
  • Una vez que uses un complemento de editor en un documento, tus colaboradores también lo verán en el menú Complementos, pero solo para ese documento (a menos que también hayan instalado ese complemento).

Este modelo de uso compartido se siente natural para la mayoría de los usuarios. Sin embargo, debido a que un complemento de editor ejecuta automáticamente su función onOpen(e) para agregar elementos de menú cuando se abre un documento, el comportamiento anterior agrega cierta complejidad a las reglas de autorización de Apps Script. Después de todo, los usuarios no se sentirían cómodos con un complemento que acceda a los datos personales cada vez que abran un documento. Esta guía te ayudará a comprender lo que puede hacer tu código y cuándo lo puede hacer.

Instalación frente a habilitada

Si ves un complemento de editor en el menú, está en uno (o ambos) estados: instalado y habilitado. Se instala un complemento de editor para un usuario en particular después de que este elige el complemento en la tienda y lo autoriza a acceder a sus datos de Google. Por el contrario, un complemento está habilitado en un documento específico cuando alguien lo usa. Si dos personas colaboran en un documento y una de ellas usa un complemento, se instala para el único usuario y se habilita para el documento.

En la siguiente tabla, se resumen los dos estados. Ten en cuenta que cuando pruebas una secuencia de comandos como un complemento, puedes elegir ejecutar la prueba en uno o en ambos estados.

Instalada Habilitados
Se aplica a Usuario Documento
Causado por Cómo obtener un complemento de la tienda Obtener un complemento de la tienda mientras usas el documento o
usar un complemento instalado anteriormente en ese documento
Menú visible para Solo a ese usuario, en todos los documentos que abra o cree Todos los colaboradores del documento
onOpen(e) se ejecuta en AuthMode.NONE (a menos que también esté habilitada, en cuyo caso AuthMode.LIMITED) AuthMode.LIMITED

Modos de autorización

Un complemento de editor ejecuta automáticamente su función onOpen(e) para agregar elementos de menú cuando se abre un documento. Sin embargo, para proteger los datos de los usuarios, Apps Script restringe lo que puede hacer la función onOpen(e). Si el complemento no se usó en el documento actual, estas restricciones se vuelven más graves.

Específicamente, los estados instalados y habilitados determinan en qué modo de autorización se ejecuta la función onOpen(e). Apps Script pasa el modo de autorización como la propiedad authMode del parámetro del evento de Apps Script, e. El valor de e.authMode corresponde a una constante en la enumeración ScriptApp.AuthMode de Apps Script.

Si se habilita un complemento de editor en el documento actual, onOpen(e) se ejecutará en AuthMode.LIMITED. Si el complemento no está habilitado y solo está instalado, onOpen(e) se ejecuta en AuthMode.NONE.

El concepto de modos de autorización se aplica a todas las ejecuciones de Apps Script, como cuando se ejecuta desde el editor de secuencias de comandos, desde un elemento de menú o desde una llamada google.script.run de Apps Script, aunque la propiedad e.authMode solo se puede inspeccionar si la secuencia de comandos se ejecuta como resultado de un activador como onOpen(e), onEdit(e) o onInstall(e). Las funciones personalizadas de Hojas de cálculo de Google usan su propio modo de autorización, AuthMode.CUSTOM_FUNCTION, que es similar a LIMITED, pero tiene restricciones ligeramente diferentes. El resto del tiempo, las secuencias de comandos se ejecutan en AuthMode.FULL, como se detalla en la tabla a continuación.

NONE LIMITED CUSTOM_FUNCTION FULL
Ocurre para onOpen(e) (si el usuario instaló un complemento, pero no lo habilitó en el documento) onOpen(e) (todos los demás horarios)
onEdit(e) (solo en Hojas de cálculo)
Funciones personalizadas Todos los demás casos, incluidos los siguientes:
activadores instalables
onInstall(e)
google.script.run
Acceso a los datos del usuario Solo configuración regional Solo configuración regional Solo configuración regional
Acceso al documento No Sí (solo lectura)
Acceso a la interfaz de usuario Agrega elementos de menú Agrega elementos de menú No
Acceso a Properties No
Acceso a Jdbc, UrlFetch No No
Otros servicios Logger
Utilities
Cualquier servicio que no acceda a datos del usuario Cualquier servicio que no acceda a datos del usuario Todos los servicios

El ciclo de vida completo

Si se instala un complemento para el usuario actual o se habilita en el documento actual, este se carga en el documento, lo que hará que aparezca en el menú de complementos y comience a detectar los activadores simples onInstall(e), onOpen(e) y onEdit(e). Si un usuario hace clic en uno de los elementos del menú del complemento, este se ejecuta.

Instalando

Cuando se instala un complemento de editor desde la tienda, su función onInstall(e) se ejecuta en AuthMode.FULL. Esto permite que el complemento ejecute una rutina de configuración compleja, pero es importante usar onInstall(e) para crear elementos de menú, ya que el documento ya está abierto y, por lo tanto, no se ejecutó tu función onOpen(e). Para tu comodidad, puedes llamar a onOpen(e) desde onInstall(e), como se muestra en este ejemplo:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Abriendo

Cuando se abre un documento, se cargan todos los complementos del editor que haya instalado el usuario actual o que cualquier colaborador haya habilitado en el documento, y llama a cada una de sus funciones de onOpen(e). El modo de autorización en el que se ejecuta onOpen(e) depende de si un complemento está instalado o habilitado.

Si un complemento solo crea un menú básico, el modo no tiene importancia. En este ejemplo, se muestra cómo se vería un onOpen(e) simple:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Sin embargo, si deseas agregar elementos de menú dinámicos en función de las propiedades almacenadas de Apps Script, leer el contenido del documento actual o realizar otras tareas avanzadas, debes detectar el modo de autorización y procesarlo de forma adecuada. En este ejemplo, se muestra cómo podría ser una función onOpen(e) avanzada que cambia su comportamiento según el modo de autorización:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Activo

Cuando alguien hace clic en uno de los elementos de menú de un complemento, Apps Script primero comprueba si el usuario instaló el complemento y le solicita que lo haga si no es así. Si el usuario autorizó el complemento, la secuencia de comandos ejecuta la función que corresponde al elemento de menú en AuthMode.FULL. El complemento también se habilita en el documento, si aún no estaba habilitado.