Autorización del complemento del editor

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

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 aparecen en el menú Extensiones, incluso si aún no los autorizó.

• Estos complementos funcionan en archivos de Google Drive que se pueden compartir con colaboradores. Los colaboradores que no tengan instalado el complemento Editor lo verán 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.

Para 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 qué 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 usa: el usuario que instaló el complemento o un colaborador.

Estados del complemento del editor

Los complementos del editor en el menú Extensiones están instalados, habilitados o ambos.

• Un complemento se instala para un usuario en particular después de que este o su administrador lo obtengan de Google Workspace Marketplace y lo autoricen para acceder a sus datos de Google.
• Un complemento se habilita en un documento, un formulario, una presentación o una hoja de cálculo cuando cualquier persona lo usa allí.
• Cuando varias personas colaboran en un archivo y una de ellas usa un complemento, este se instala para el usuario y se habilita para el archivo.

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

Modos de autorización

La función onOpen() de un complemento de 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 Editor determina en qué modo de autorización se ejecuta la función onOpen().

Si un complemento de Editor está habilitado en el archivo, formulario, presentación o 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úa con él haciendo clic o ejecutando funciones personalizadas. Si tu complemento intenta usar estos servicios en onOpen(), onInstall() o en el alcance global, los permisos fallan y se detienen otras llamadas, como la compilación de menús. Ayuda es la única opción compatible.

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ú, solo se ejecutan en este modo. Después de que se ejecuta el código en el modo AuthMode.FULL, el complemento puede usar todos los permisos 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 secuencia 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 en 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. En todos los demás casos, las secuencias de comandos se ejecutan en AuthMode.FULL, como se describe en la siguiente tabla.

Ciclo de vida de la 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 escuchar los activadores simples onInstall(), onOpen() y onEdit(). Si un usuario hace clic en un elemento del menú Extensiones, se ejecuta.

Se instala 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 tu función onOpen() no se ejecutó. 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 abre el complemento del editor

Cuando se abre un documento, un formulario, una presentación o una hoja de cálculo, se carga cada complemento de 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ámicos basados en propiedades de Apps Script almacenadas, leer el contenido del archivo actual o realizar otras tareas avanzadas, debes identificar el modo de autorización y controlarlo 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 paneles laterales y diálogos, ya que se ejecutan en AuthMode.FULL.

Un usuario ejecuta el complemento Editor

Cuando un usuario hace clic en un elemento de menú Extensiones, Apps Script primero verifica 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 se habilita en el documento, el formulario, la presentación o la hoja de cálculo si aún no lo estaba.

Soluciona problemas relacionados con la no renderización de los menús de complementos

Es posible que el menú del complemento no se renderice si tu código no administra los modos de autorización correctamente. 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 causa 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 o objetos de Apps Script 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, retíralo o unelo en un bloque de comentarios. Deja solo estos métodos: .getUi(), .createMenu(), .addItem() y .addToUi(). También busca y quita cualquier servicio que no esté dentro 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 particular 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 Config esté instalado para el usuario actual y que el texto debajo del cuadro Config diga Probar en AuthMode.None.

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

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

Temas relacionados

• Apps web
• Tipos de complementos
• Cómo probar un complemento de Editor