Se usó la API de Cloud Translation para traducir esta página.

Autorización para el complemento del editor

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

El modelo de autorización de 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 tienen instalado el complemento Editor lo ven en los documentos en los que lo 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 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 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, un formulario, una presentación o una hoja de cálculo cuando cualquier persona lo usa 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 instalado y habilitado. Ten en cuenta que cuando probar una secuencia de comandos como un 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 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 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 el alcance global, los permisos fallan y se detienen otras llamadas, como completar menús. Ayuda es la única opción compatible.

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 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 se ejecuta la secuencia de comandos 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. 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 para	`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	En cualquier otro momento, 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 un documento, un formulario, una presentación o una hoja de cálculo	No	Sí	Sí, solo lectura	Sí
Acceso a la interfaz de usuario	Cómo agregar elementos de menú	Cómo agregar elementos del 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 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 la autorización de un complemento del 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 elemento del menú Extensiones, se ejecuta.

El complemento del editor está instalado

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, 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 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 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 que onOpen() depende de si se ejecuta un complemento instalada o habilitada.

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 estos 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ú en AuthMode.FULL. El el complemento esté habilitado en el documento, formulario presentación u 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 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 causa errores de permisos en AuthMode.NONE, prueba las siguientes acciones:

Abre el proyecto de Apps Script de tu complemento y busca la función onOpen().
Busca en la función onOpen() menciones de servicios o objetos de Apps Script asociados con ellos, como PropertiesService, SpreadsheetApp o GmailApp.
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(). También busca y quita cualquier servicio que no esté dentro de una función.
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. Reorganiza o reescribe tu base de código para que se adapte a los cambios realizados en los pasos anteriores.
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
Inicia la implementación de prueba y abre el menú Extensiones.
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.