Autorização de complementos do editor

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Na maioria dos casos, é preciso autorizar um complemento antes de usá-lo. Em muitos projetos do Apps Script, como apps da Web, a autorização é simples. O projeto de script solicita todas as permissões necessárias quando você tenta usá-lo. Depois de autorizado, você pode usar o projeto de script livremente. Todos que usam o projeto de script o autorizam separadamente.

O modelo de autorização dos complementos do editor é mais complexo. Como esses complementos funcionam em arquivos que residem no Google Drive (arquivos que podem ser compartilhados com outras pessoas), você precisa criar complementos do editor com os diferentes modos de autorização em mente. Os aplicativos do editor do Google Workspace também oferecem um menu Complementos na IU, que é preenchido pelos complementos instalados, mesmo que você ainda não tenha autorizado esses complementos. Isso aumenta a complexidade do modelo.

Modelo de autorização

Duas propriedades de complementos de editor facilitam o compartilhamento e o uso:

  • Depois de instalar um complemento do editor na loja, você o verá no menu "Complementos" para cada documento que abrir ou criar. Os colaboradores desses documentos não verão o complemento, exceto nos documentos em que você o usa.
  • Depois que você usa um complemento de editor em um documento, os colaboradores também o veem no menu "Complementos", mas somente para esse documento (a menos que também tenham instalado esse complemento).

Este modelo de compartilhamento parece natural para a maioria dos usuários. No entanto, como um complemento do editor executa automaticamente a função onOpen(e) para adicionar itens de menu quando um documento é aberto, o comportamento acima adiciona alguma complexidade às regras de autorização do Apps Script. Afinal, os usuários não se sentiriam confortáveis com um complemento que acessa dados pessoais sempre que abrirem um documento. Este guia ajuda você a entender o que o código pode fazer e quando.

Instalado x ativado

Se você vir um complemento de editor no menu, ele estará em um (ou ambos) de dois estados: instalado e ativado. Um complemento do editor é instalado para um usuário específico depois que ele escolhe o complemento na loja e o autoriza a acessar os dados do Google dele. Por outro lado, um complemento é ativado em um determinado documento quando alguém o usa. Se duas pessoas colaboram em um documento e uma delas usa um complemento, ele é instalado para um usuário e ativado para o documento.

A tabela abaixo resume os dois estados. Ao testar um script como complemento, você pode optar por executar o teste em um ou ambos os estados.

Instalado Ativado
Válido para Usuário Documentos
Causado por Como instalar um complemento na loja Instalar um complemento da loja ao usar o documento ou
Usar um complemento instalado anteriormente no documento
Menu visível para Só o usuário, em todos os documentos que ele abre ou cria Todos os colaboradores desse documento
onOpen(e) corridas em AuthMode.NONE (a menos que ativado também), nesse caso AuthMode.LIMITED) AuthMode.LIMITED

Modos de autorização

Um complemento do editor executa automaticamente a função onOpen(e) para adicionar itens de menu quando um documento é aberto, mas para proteger os dados dos usuários, o Apps Script restringe o que a função onOpen(e) pode fazer. Se o complemento não tiver sido usado no documento atual, essas restrições se tornarão mais graves.

Especificamente, os estados instalados e ativados determinam em qual modo de autorização a função onOpen(e) é executada. O Apps Script transmite o modo de autorização como a propriedade authMode do parâmetro de evento do Apps Script, e. O valor de e.authMode corresponde a uma constante na enumeração ScriptApp.AuthMode do Apps Script.

Se um complemento do editor estiver ativado no documento atual, o onOpen(e) será executado em AuthMode.LIMITED. Se o complemento não estiver ativado e estiver instalado apenas, onOpen(e) será executado em AuthMode.NONE.

O conceito de modos de autorização se aplica a todas as execuções do Apps Script, como a execução no editor de script, em um item de menu ou na chamada google.script.run do Apps Script, embora a propriedade e.authMode só possa ser inspecionada se o script for executado como resultado de um gatilho como onOpen(e), onEdit(e) ou onInstall(e). As funções personalizadas no Planilhas Google usam o próprio modo de autorização, AuthMode.CUSTOM_FUNCTION, que é semelhante a LIMITED, mas tem restrições um pouco diferentes. O restante tempo, os scripts são executados em AuthMode.FULL, conforme detalhado na tabela abaixo.

NONE LIMITED CUSTOM_FUNCTION FULL
Ocorre por onOpen(e) (se o usuário tiver instalado um complemento, mas não tiver ativado esse complemento no documento) onOpen(e) (todos os outros horários)
onEdit(e) (somente no Planilhas)
Funções personalizadas Todos os outros horários, incluindo:
acionadores instaláveis
onInstall(e)
google.script.run
Acesso aos dados do usuário Apenas localidade Apenas localidade Apenas localidade Sim
Acesso ao documento No Sim Sim (somente leitura) Sim
Acesso à interface do usuário Adicionar itens do cardápio Adicionar itens do cardápio No Sim
O acesso a Properties No Sim Yes Sim
Acesso a Jdbc, UrlFetch No Não Sim Sim
Outros serviços Logger
Utilities
Todos os serviços que não acessam dados do usuário Todos os serviços que não acessam dados do usuário Todos os serviços

O ciclo de vida completo

Se um complemento for instalado para o usuário atual ou ativado no documento atual, ele será carregado no documento, o que faz com que ele apareça no menu "Complementos" e comece a detectar os acionadores simples onInstall(e), onOpen(e) e onEdit(e). Se um usuário clicar em um dos itens de menu do complemento, ele será executado.

Instalando

Quando um complemento do editor é instalado a partir da loja, a função onInstall(e) é executada em AuthMode.FULL. Isso permite que o complemento execute uma rotina de configuração complexa, mas é importante usar onInstall(e) para criar itens de menu, já que o documento já está aberto e, portanto, a função onOpen(e) não é executada. Por conveniência, você pode chamar onOpen(e) de onInstall(e), como mostrado neste exemplo:

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

Abertura

Quando um documento é aberto, ele carrega todos os complementos do editor que o usuário atual instalou ou que qualquer colaborador ativou no documento e chama cada uma das funções de onOpen(e). O modo de autorização no qual onOpen(e) é executado dependendo se um complemento está instalado ou ativado.

Se um complemento criar apenas um menu básico, o modo não importa. Este exemplo mostra como é uma onOpen(e) simples:

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

No entanto, se você quiser adicionar itens de menu dinâmicos com base nas propriedades armazenadas do Apps Script, ler o conteúdo do documento atual ou realizar outras tarefas avançadas, será necessário detectar o modo de autorização e processá-lo adequadamente. Este exemplo mostra como pode ser uma função onOpen(e) avançada, alterando o comportamento dela com base no modo de autorização:

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();
}

Em execução

Quando alguém clica em um dos itens do menu de um complemento, o Apps Script verifica primeiro se o usuário instalou o complemento e solicita que ele faça isso. Se o usuário autorizou o complemento, o script executa a função que corresponde ao item de menu em AuthMode.FULL. O complemento também é ativado no documento, se ainda não foi ativado.