Autorización para el complemento del editor

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

El modelo de autorización para Los Complementos del editor son puede ser más complejo por varias razones:

  • 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 puede compartir con colaboradores. Los colaboradores que no instalar el complemento de Editor y verlo en los documentos dónde la usó el creador del archivo.

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

Para proteger los datos del usuario, se aplican modos de autorización que hacen que algunos servicios no disponible para onOpen(). Esta guía puede ayudarte a entender cuál es tu código puedes hacer y cuándo.

Modelo de autorización

El modo de autorización de un complemento de editor depende de lo siguiente: 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 del editor en el menú Extensiones tienen las siguientes características: instalado, habilitado o ambos.

  • Se instala un complemento para una aplicación usuario después de que ellos o el administrador la obtengan del Google Workspace Marketplace y autorizarlo para acceder a sus datos de Google
  • Un complemento se habilita en un documento, formulario una presentación u hoja de cálculo cuando alguien la use allí.
  • Cuando una persona colabora en un archivo y una de ellas usa un esté instalado para un usuario individual y enabled para el archivo.

En la siguiente tabla, se resumen las diferencias entre las versiones instaladas y habilitadas. Ten en cuenta que cuando probar una secuencia de comandos como un complemento puedes ejecutar la prueba en uno o ambos estados.

Instalada Habilitada
Se aplica a Usuario Documento, formulario, presentación u hoja de cálculo
Causado por Obtener un complemento de la tienda Obtener un complemento de la tienda mientras se 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 bien hojas de cálculo que abran o creen Todos los colaboradores de ese documento, formulario, presentación o una hoja de cálculo
Modo de autorización para onOpen() AuthMode.NONE
(a menos que también esté habilitada, en cuyo caso AuthMode.LIMITED)
AuthMode.LIMITED

Modos de autorización

Se ejecuta la función onOpen() de un complemento de editor automáticamente cuando un usuario abre un documento, formulario, presentación u hoja de cálculo. Para proteger las contraseñas Apps Script restringe lo que onOpen() puede hacer. 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, haz lo siguiente: formulario, presentación u hoja de cálculo, onOpen() se ejecuta AuthMode.LIMITED Si el complemento no está habilitado y se muestra Solo instalada, onOpen() se ejecuta en AuthMode.NONE.

En AuthMode.NONE, un complemento no puede ejecutar ciertos hasta que el usuario interactúe con el complemento hacer clic o ejecutar funciones personalizadas. Si el el complemento intenta usar estos servicios en onOpen(), onInstall(), o de permiso global, los permisos fallan y otras llamadas, como rellenando los menús, detente. La opción de ayuda es la única opción admitida.

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

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

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 secuencia de comandos Llamada google.script.run. Sin embargo, La propiedad e.authMode solo se puede inspeccionar si se ejecuta la secuencia de comandos como resultado. de un activador, como onOpen(), onEdit() o onInstall(). 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. Para todos En otros casos, las secuencias de comandos se ejecutan en AuthMode.FULL, como se describe a continuación desde una tabla de particiones.

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

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

Cuando se instala un complemento para el usuario actual o está habilitado en el archivo actual, el complemento se carga para el documento, formulario, presentación o una hoja de cálculo cuando se abra ese archivo. El complemento es que se encuentra en el menú Extensiones y comienza a escuchar el activadores simples onInstall(), onOpen() y onEdit(). Si un usuario hace clic en un El elemento de menú Extensions (Extensiones), se ejecuta.

El complemento del editor está instalado

Cuando se instala un complemento del editor desde la tienda, La función onInstall() se ejecuta en AuthMode.FULL. En este modo de autorización, 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á abierta y la función onOpen() no se ejecutó. En el siguiente ejemplo, se muestra cómo llamar a la función onOpen() de 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, formulario, hoja de cálculo o presentación, se carga cada complemento del editor que el usuario actual instaló o que cualquier colaborador haya habilitado en el archivo, y invoca cada una de sus funciones onOpen(). El modo de autorización que onOpen() depende de si se ejecuta un complemento instalada o habilitada.

Si un complemento solo crea un menú básico, la ventana de 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 en función de la secuencia de comandos almacenada de Apps Script properties, para leer el contenido de la archivo actual o para 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 basada en 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 los 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ó complemento y si no, 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ú de AuthMode.FULL. El el complemento esté habilitado en el documento, formulario presentación u hoja de cálculo, si aún no lo estaba.

Cómo solucionar problemas relacionados con la renderización de menús de complementos

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

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

  • Un complemento intenta ejecutar una llamada de servicio antes que un usuario interactúa 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 Apps Script de tu complemento y busca la función onOpen().
  2. Busca menciones de Apps Script en la función onOpen() servicios u objetos asociados con ellos, como PropertiesService, SpreadsheetApp o GmailApp.
  3. Si un servicio se usa para cualquier otro fin que no sea crear los elementos de la IU, quitarlo o unirlo 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. Identificar funciones que podrían contener las líneas de código comentadas o eliminadas en el paso anterior, particularmente aquellos que usan la información que producen y mover las llamadas de servicio a las funciones que las necesitan. Reordenar o reescribir tu base de código para adaptarse 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é Instalado para el usuario actual y que el texto debajo del cuadro Configuración 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ú, se solucionó el problema. Si solo ves el menú Ayuda, regresa al paso 1. Es posible que hayas perdido una llamada de servicio.