Autorización de complemento de editor

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 la secuencia de comandos solicita cualquier permiso que falte cuando intentas usarlo. Una vez autorizado, puedes usar el proyecto de secuencia de comandos con libertad. Todos los que usan el proyecto de la 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 se encuentran en Google Drive (archivos que se pueden compartir con otras personas), debes compilar complementos de Editor con los diferentes modos de autorización en mente. Los editores de Documentos de Google también proporcionan un menú de Complementos en sus IU que se propaga mediante los complementos que instalaste, incluso si aún no autorizaste esos complementos. Esto agrega complejidad adicional al modelo de autorización.

Modelo de autorización

Dos propiedades de complementos de Editores los hacen especialmente fáciles de compartir y de usar:

• Cuando obtengas un complemento de editor de la tienda, lo verás en el menú de complementos para cada documento, formulario, presentación o hoja de cálculo que abras o crees. Los colaboradores no verán el complemento, excepto en los documentos, los formularios, las presentaciones o las hojas de cálculo en los que realmente lo uses.
• Una vez que uses un complemento de editor en un documento, formulario, presentación o hoja de cálculo, tus colaboradores también lo verán en el menú de complementos, pero solo para ese archivo (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 editor de Documentos de Google, 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 datos personales cada vez que abran un documento, formulario, presentación o hoja de cálculo. Esta guía debería ayudarte a comprender lo que puede hacer tu código y cuándo.

Instalado o habilitado

Si ves un complemento de editor en el menú, significa que tienes uno (o ambos) instalado: habilitado y habilitado. Se instala un complemento de editor para un usuario en particular después de que 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, formulario, presentación o hoja de cálculo determinado cuando alguien lo usa. Si dos personas colaboran y una de ellas usa un complemento, se instalará para el usuario individual y se habilitará para el archivo.

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 de estos estados o en ambos.

	Instalada	Habilitada
Se aplica a	Usuario	Documento, formulario, presentación u hoja de cálculo
Causado por	Cómo obtener un complemento de la tienda	Obtener un complemento de la tienda mientras se usa ese documento, formulario, presentación o hoja de cálculo, o bien Usar un complemento instalado anteriormente en ese documento, formulario, presentación o hoja de cálculo
Menú visible para	Solo ese usuario, en todos los documentos, formularios, presentaciones o hojas de cálculo que abra o cree	Todos los colaboradores de ese documento, formulario, presentación o hoja de cálculo
onOpen(e) se ejecuta	AuthMode.NONE (a menos que también esté habilitado, 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, formulario, presentación o hoja de cálculo, pero 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, formulario, presentación o hoja de cálculo actual, estas restricciones se vuelven más graves.

En particular, 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, que es e. El valor de e.authMode corresponde a una constante en el tipo enum de ScriptApp.AuthMode de Apps Script.

Si se habilita un complemento de editor en el documento, formulario, presentación o hoja de cálculo 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.

Nota: Solo los complementos de editor publicados pueden estar en AuthMode.NONE; sin publicar, los complementos de editor se ejecutan onOpen(e) en AuthMode.LIMITED. Sin embargo, puedes probar un complemento de editor para verificar que un complemento en desarrollo se comporte según lo previsto en AuthMode.

El concepto de modos de autorización se aplica a todas las ejecuciones de Apps Script, como la ejecución 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 un poco diferentes. El resto del tiempo, las secuencias de comandos se ejecutan en AuthMode.FULL, como se detalla en la siguiente tabla.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Se produce durante	onOpen(e) (si el usuario instaló un complemento, pero no lo habilitó en el documento, el formulario, la presentación o la hoja de cálculo)	onOpen(e) (todos los demás horarios) onEdit(e) (solo en Hojas de cálculo)	Funciones personalizadas	Todos los demás horarios, 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	Sí
Acceso a documentos, formularios, presentaciones o hojas de cálculo	No	Sí	Sí (solo lectura)	Sí
Acceso a la interfaz de usuario	Agrega elementos de menú	Agrega elementos de menú	No	Sí
Acceso a Properties	No	Sí	Sí	Sí
Acceso a Jdbc, UrlFetch	No	No	Sí	Sí
Otros servicios	Logger Utilities	Cualquier servicio que no acceda a los datos del usuario	Cualquier servicio que no acceda a los datos del usuario	All services

El ciclo de vida completo

Si se instaló un complemento para el usuario actual o se habilitó en el archivo actual, se cargará en el documento, el formulario, la presentación o la hoja de cálculo, lo que hará que aparezca en el menú de complementos y comience a escuchar los activadores simples onInstall(e), onOpen(e) y onEdit(e). Si un usuario hace clic en uno de los elementos del menú del complemento, se ejecuta.

Instalando

Cuando se instala un complemento de editor desde Store, su función onInstall(e) se ejecuta en AuthMode.FULL. Esto permite que el complemento ejecute una rutina de configuración compleja, pero también es importante usar onInstall(e) para crear elementos de menú, ya que el documento, el formulario, la presentación o la hoja de cálculo ya están abiertos y, por lo tanto, no se ejecutó la función onOpen(e). Para mayor 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, formulario, presentación o hoja de cálculo, se carga cada complemento de editor que el usuario actual instaló o que cualquier colaborador habilitó en el archivo, y llama a cada una de sus funciones 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 importa. En este ejemplo, se muestra cómo podría ser 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ámico basados en las propiedades almacenadas de Apps Script, leer el contenido del documento, el formulario, la presentación o la hoja de cálculo actual, o realizar otras tareas avanzadas, debes detectar el modo de autorización y manejarlo de forma adecuada. En este ejemplo, se muestra cómo podría ser una función onOpen(e) avanzada, lo que cambia su comportamiento en función del 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();
}

Advertencia: Cuando se ejecuta tu función onOpen(e), se carga toda la secuencia de comandos y se ejecutan todas las sentencias globales. Estas declaraciones se ejecutan en el mismo modo de autorización que onOpen(e) y fallan si el modo las prohíbe. Esto evita que se ejecute onOpen(e). Si tu complemento publicado no puede agregar sus elementos de menú, consulta la consola de JavaScript del navegador para ver si se produjo un error y, luego, examina la secuencia de comandos a fin de ver si la función onOpen(e) o las variables globales llaman a servicios no permitidos en AuthMode.NONE.

Nota: Los complementos no pueden abrir barras laterales ni diálogos mientras se ejecutan en AuthMode.LIMITED. Puedes usar elementos de menú para abrir barras laterales y diálogos, ya que se ejecutan en AuthMode.FULL.

En ejecución

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 pide que lo haga. Si el usuario autorizó el complemento, la secuencia de comandos ejecutará la función que corresponde al elemento de menú en AuthMode.FULL. El complemento también se habilita en el documento, formulario, presentación o hoja de cálculo, si aún no estaba habilitado.