Autorización de complemento de editor

La autorización para muchas apps basadas en Apps Script es sencilla porque el proyecto de secuencia de comandos solicita los permisos faltantes que necesita cuando alguien intenta usarla.

El modelo de autorización para los complementos de Editor es más complejo por varios motivos:

  • Cuando un usuario crea un archivo, todos los complementos que instala se enumeran en el menú Extensiones, incluso si el usuario aún no autorizó esos complementos.

  • Estos complementos funcionan en archivos de Google Drive que se pueden compartir con colaboradores. Los colaboradores que no tienen instalado el complemento de editor lo ven en los documentos en los que lo usó el creador del archivo.

  • Los complementos de Editor ejecutan automáticamente sus funciones onOpen() cuando se abre un documento.

A fin de proteger los datos del usuario, se aplican modos de autorización que hacen que algunos servicios no estén disponibles para onOpen(). Esta guía puede ayudarte a comprender lo que puede hacer tu código y cuándo.

Modelo de autorización

El modo de autorización de un complemento de editor depende de su estado, que depende de quién lo use: el usuario que instaló el complemento o un colaborador.

Estados del complemento del editor

Los complementos de Editor en el menú Extensiones están instalados o habilitados, o bien ambas opciones.

  • Un complemento se instala para un usuario en particular después de que este o su administrador lo obtiene de Google Workspace Marketplace y lo autoriza a acceder a sus datos de Google.
  • Un complemento está habilitado en un documento, formulario, hoja de cálculo o presentación cuando alguien lo usa allí.
  • Cuando las personas colaboran en un archivo y uno de ellos usa un complemento, este se instala para el usuario y se habilita para el archivo.

En la siguiente tabla, se resumen las diferencias entre la versión instalada y la habilitada. Ten en cuenta que cuando pruebas una secuencia de comandos como un complemento puedes ejecutar la prueba en uno de estos estados o en ambos.

Instalado Habilitada
Se aplica a Usuario Documento, formulario, presentación u hoja de cálculo
Causado por Obteniendo un complemento de la tienda Obtener un complemento de la tienda mientras usas ese documento, formulario, presentación o hoja de cálculo, o bien
Usar un complemento instalado previamente en ese documento, formulario, presentación o hoja de cálculo
Menú visible para Solo ese usuario, en todos los documentos, formularios, hojas de cálculo o presentaciones que abra o cree Todos los colaboradores de ese documento, formulario, presentación u hoja de cálculo
Modo de autorización para onOpen() AuthMode.NONE
(a menos que también esté habilitado, en cuyo caso es AuthMode.LIMITED))
AuthMode.LIMITED

Modos de autorización

La función onOpen() de un complemento del editor se ejecuta automáticamente cuando un usuario abre un documento, un formulario, una presentación o una hoja de cálculo. Para proteger los datos de los usuarios, Apps Script restringe lo que puede hacer la función onOpen(). El estado del complemento del editor determina en qué modo de autorización se ejecuta la función onOpen().

Si un complemento del editor está habilitado en el archivo, el formulario, la presentación o la hoja de cálculo, onOpen() se ejecuta en AuthMode.LIMITED. Si el complemento no está habilitado y solo está instalado, onOpen() se ejecuta en AuthMode.NONE.

En AuthMode.NONE, un complemento no puede ejecutar ciertos servicios hasta que el usuario interactúe con él haciendo clic o ejecutando funciones personalizadas. Si tu complemento intenta usar estos servicios en onOpen(), onInstall() o el alcance global, los permisos fallan y otras llamadas, como completar menús, se detienen. La ayuda es la única opción admitida.

Para ejecutar llamadas de servicio restringidas, debes usar el modo de autorización AuthMode.FULL. Las funciones de interacción del usuario, como hacer clic en una opción de menú, se ejecutan solo en este modo. Después de ejecutar el código en modo AuthMode.FULL, el complemento puede usar todos los alcances que autorizó el usuario.

Apps Script pasa el modo de autorización como la propiedad authMode del parámetro de evento de Apps Script, e. El valor de e.authMode corresponde a una constante en la enumeración ScriptApp.AuthMode de Apps Script.

Los modos de autorización se aplican a todos los métodos de ejecución de Apps Script, incluida 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. Sin embargo, la propiedad e.authMode solo se puede inspeccionar si la secuencia de comandos se ejecuta como resultado de un activador, como onOpen(), onEdit() o onInstall(). 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. En todos los demás casos, las secuencias de comandos se ejecutan en AuthMode.FULL, como se describe en la siguiente tabla.

NONE LIMITED CUSTOM_FUNCTION FULL
Ocurre para onOpen() (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() (todos los demás horarios)
onEdit() (solo en Hojas de cálculo)
Funciones personalizadas En todos los demás casos, incluidos los siguientes:
activadores instalables
onInstall()
google.script.run
Acceso a los datos del usuario Solo configuración regional Solo configuración regional Solo configuración regional
Acceso a documentos, formularios, hojas de cálculo o presentaciones No Sí, solo lectura
Acceso a la interfaz de usuario Cómo agregar productos del menú Cómo agregar productos del menú No
Acceso a Properties No
Acceso a Jdbc y UrlFetch No No
Otros servicios Logger
Utilities
Cualquier servicio que no acceda a los datos del usuario Cualquier servicio que no acceda a los datos del usuario Todos los servicios

Ciclo de vida de autorización de un complemento del editor

Cuando se instala un complemento para el usuario actual o se habilita en el archivo actual, se carga para el documento, el formulario, la presentación o la hoja de cálculo cuando se abre ese archivo. El complemento se muestra en el menú Extensiones y comienza a detectar los activadores simples onInstall(), onOpen() y onEdit(). Si un usuario hace clic en un elemento del menú Extensiones, se ejecuta.

Se instaló el complemento del editor

Cuando se instala un complemento de editor desde la tienda, su función onInstall() se ejecuta en AuthMode.FULL. En este modo de autorización, el complemento puede ejecutar una rutina de configuración compleja. También debes usar onInstall() 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 no se ejecutó la función onOpen(). En el siguiente ejemplo, se muestra cómo llamar a la función onOpen() desde la función onInstall():

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

Se abrió el complemento del editor

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

Si un complemento solo crea un menú básico, el modo no importa. En el siguiente ejemplo, se muestra una función onOpen() básica:

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

Para agregar elementos de menú dinámico basados en propiedades almacenadas de Apps Script, leer el contenido del archivo actual o realizar otras tareas avanzadas, debes identificar el modo de autorización y manejarlo de forma adecuada.

En el siguiente ejemplo, se muestra una función onOpen() avanzada que cambia su acción 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();
}

Ten en cuenta que 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.

Un usuario ejecuta el complemento del editor

Cuando un usuario hace clic en un elemento de menú Extensiones, Apps Script primero verifica si el usuario instaló el complemento y, si no lo hizo, le pide que lo haga. 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 está habilitado en el documento, el formulario, la presentación o la hoja de cálculo, si aún no lo estaba.

Cómo solucionar problemas de renderización en menús de complementos

Es posible que el menú de complementos no se renderice si el código no administra correctamente los modos de autorización. Por ejemplo:

  • Un complemento intenta ejecutar un servicio de Apps Script que no es compatible con el modo de autorización actual.

  • Un complemento intenta ejecutar una llamada de servicio antes de que un usuario interactúe con él.

Para quitar o reorganizar una llamada de servicio que está causando errores de permisos en AuthMode.NONE, prueba las siguientes acciones:

  1. Abre el proyecto de Apps Script de tu complemento y busca la función onOpen().
  2. Busca en la función onOpen() menciones de servicios de Apps Script u objetos asociados con ellos, como PropertiesService, SpreadsheetApp o GmailApp.
  3. Si un servicio se usa para algo que no sea crear los elementos de la IU, quítalo o únelo en un bloque de comentarios. Deja solo estos métodos: .getUi(), .createMenu(), .addItem() y .addToUi(). Además, busca y quita cualquier servicio que esté fuera de una función.
  4. Identifica las funciones que podrían contener las líneas de código comentadas o quitadas en el paso anterior, en especial, aquellas que usan la información que producen, y mueve las llamadas de servicio a las funciones que las necesitan. Reorganiza o reescribe tu base de código para que se adapte a los cambios realizados en los pasos anteriores.
  5. Guarda el código y crea una implementación de prueba.

    Cuando crees una implementación de prueba, asegúrate de que el campo Configuración esté Installed for current user y que el texto debajo del cuadro de configuración diga Test in AuthMode.None.

  6. Inicia la implementación de prueba y abre el menú Extensions (Extensiones).

  7. Si se muestran todos los elementos del menú, el problema ya se solucionó. Si solo ves el menú Ayuda, regresa al paso 1. Es posible que hayas perdido una llamada de servicio.