Autorização de complementos do Editor

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

O modelo de autorização dos Complementos de editor é mais complexo. Como esses complementos funcionam em arquivos que residem no Google Drive (arquivos que podem ser compartilhados com outros), você precisa criar complementos de 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 de autorização.

Modelo de autorização

Duas propriedades dos complementos do Editor facilitam o compartilhamento e o uso:

• Depois de instalar um complemento do Editor na loja, você o verá no menu de complementos de cada documento aberto ou criado. Os colaboradores nesses documentos não verão o complemento, exceto nos documentos em que você realmente o utiliza.
• Quando você usa um complemento do Editor em um documento, seus colaboradores também o veem no menu de complementos, mas apenas para esse documento, a menos que também tenham instalado esse complemento.

Esse modelo de compartilhamento é 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 ficariam à vontade com um complemento que acessa dados pessoais toda vez que abrem um documento. Este guia ajudará você a entender o que seu código pode fazer e quando.

Instalado x ativado

Se você vir um complemento do editor no menu, ele está em um (ou ambos) 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. Por outro lado, um complemento é ativado em um determinado documento quando alguém o usa. Se duas pessoas colaborarem em um documento e uma delas usar um complemento, ele será instalado para o usuário e ativado para o documento.

A tabela abaixo resume os dois estados. Observe que, 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 já instalado no documento
Menu visível para	Somente esse usuário, em todos os documentos que ele abre ou cria	Todos os colaboradores do documento
onOpen(e) corridas em	AuthMode.NONE (a menos que também esteja ativado, caso em que 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 ficarão mais graves.

Especificamente, os estados de instalação e ativação 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 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 em uma 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 tempo restante, os scripts são executados em AuthMode.FULL, conforme detalhado na tabela abaixo.

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

O ciclo de vida completo

Se um complemento foi instalado para o usuário atual ou ativado no documento atual, o complemento é carregado no documento, o que faz com que ele apareça no menu de 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 também usar a onInstall(e) para criar itens de menu, já que o documento já está aberto e, portanto, sua função onOpen(e) não foi executada. Por conveniência, chame onOpen(e) a partir de onInstall(e), conforme mostrado neste exemplo:

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

Abertura

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

Se um complemento cria apenas um menu básico, o modo não importa. Este exemplo mostra como seria um 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 executar outras tarefas avançadas, precisará detectar o modo de autorização e processá-lo corretamente. Este exemplo mostra como pode ser uma função onOpen(e) avançada, mudando 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 de menu de um complemento, o Apps Script primeiro verifica se o usuário instalou o complemento e solicita que ele faça isso. Se o usuário tiver autorizado o complemento, o script executará a função que corresponde ao item de menu em AuthMode.FULL. O complemento também é ativado no documento, caso ainda não tenha sido.