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 faltantes que necesita cuando alguien intenta usarlo.

El modelo de autorización para los complementos del 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 Editor lo ven en los documentos en los que el creador del archivo lo usó.

• Los complementos del Editor ejecutan automáticamente sus funciones de 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 del Editor depende de su estado, que, a su vez, depende de quién lo use: 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 él o su administrador lo obtienen de Google Workspace Marketplace y lo autorizan para acceder a sus datos de Google.
• Un complemento está habilitado en un documento, formulario, presentación u hoja de cálculo cuando alguien lo usa allí.
• Cuando varias personas colaboran en un archivo y una de ellas usa un complemento, este se instala para ese 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 estados.

	Instalada	Habilitado
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 usa ese documento, formulario, presentación u hoja de cálculo, o Usar un complemento instalado previamente en ese documento, formulario, presentación u 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
Modo de autorización para onOpen()	AuthMode.NONE (a menos que también esté habilitado, en cuyo caso 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, formulario, presentación u 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 el alcance de onOpen(), onInstall() o global, los permisos fallan y se detienen otras llamadas, como las de completar menús. La única opción admitida es Help.

Para ejecutar llamadas a servicios restringidos, 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.

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

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, lo que incluye la ejecución desde el editor de secuencias de comandos, desde un elemento de menú o desde una llamada de 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.

	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() (en todos los demás momentos) 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	Sí
Acceso a documentos, formularios, presentaciones u hojas de cálculo	No	Sí	Sí (solo lectura)	Sí
Acceso a la interfaz de usuario	Cómo agregar productos del menú	Cómo agregar productos del menú	No	Sí
Acceso a Properties	No	Sí	Sí	Sí
Acceso a Jdbc, UrlFetch	No	No	Sí	Sí
Otros servicios	Logger Utilities	Todos los servicios que no acceden a los datos del usuario	Todos los servicios que no acceden a los datos del usuario	Todos los servicios

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, el complemento se carga en el documento, el formulario, la presentación o la hoja de cálculo cuando se abre ese archivo. El complemento aparece 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.

El complemento del Editor está instalado

Cuando se instala un complemento del 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 del Editor que el usuario actual haya instalado o que cualquier colaborador haya habilitado 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 el 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 almacenadas de Apps Script, 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();
}

Advertencia: Cuando se ejecuta la función onOpen(), se carga todo el script y todas las instrucciones globales se ejecutan en el mismo modo de autorización que onOpen(). Si el modo de autorización prohíbe las instrucciones globales, tanto las instrucciones globales como onOpen() no se ejecutarán. Si el complemento publicado no agrega sus elementos de menú, revisa la consola de JavaScript del navegador para ver si se devolvió un error. Luego, examina tu secuencia de comandos para ver si la función onOpen() o las variables globales llaman a servicios que no se permiten en AuthMode.NONE.

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 estos se ejecutan en AuthMode.FULL.

Un usuario ejecuta el complemento del Editor

Cuando un usuario hace clic en un elemento de menú de Extensiones, Apps Script primero verifica si el usuario instaló el complemento y, si no lo hizo, le solicita 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 se habilitará 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ú de complementos 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 está causando errores de permisos en AuthMode.NONE, intenta realizar 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 de objetos de Apps Script asociados con ellos, como PropertiesService, SpreadsheetApp o GmailApp.
3. Si un servicio se usa para algo más que crear los elementos de la IU, quítalo o envuélvelo en un bloque de comentarios. Deja solo estos métodos: .getUi(), .createMenu(), .addItem() y .addToUi(). También 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 las que usan la información que producen, y mueve las llamadas de servicio a las funciones que las necesiten. Reorganiza o reescribe tu base de código para adaptarla 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é establecido como Installed for current user y de 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ú Extensiones.

7. Si se muestran todos los elementos del menú, el problema se solucionó. 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 del Editor