Autorização do complemento do editor

A autorização para muitos apps baseados no Apps Script é simples porque o projeto de script pede as permissões necessárias quando alguém tenta usá-lo.

O modelo de autorização para complementos do editor é mais complexo por vários motivos:

• Quando um usuário cria um arquivo, todos os complementos instalados por ele são listados no menu Extensões, mesmo que ainda não tenham sido autorizados.

• Esses complementos funcionam em arquivos do Google Drive que podem ser compartilhados com colaboradores. Os colaboradores que não têm o complemento Editor instalado vão vê-lo em documentos em que o criador do arquivo o usou.

• Os complementos do Editor executam automaticamente as funções onOpen() quando um documento é aberto.

Para proteger os dados do usuário, são aplicados modos de autorização que tornam alguns serviços indisponíveis para onOpen(). Este guia pode ajudar você a entender o que seu código pode fazer e quando.

Modelo de autorização

O modo de autorização de um complemento do Editor depende do estado dele, que depende de quem está usando: o usuário que instalou o complemento ou um colaborador.

Estados do complemento do editor

Os complementos do editor no menu Extensões estão instalados, ativados ou ambos.

• Um complemento é instalado para um determinado usuário depois que ele ou o administrador dele o recebe do Google Workspace Marketplace e autoriza o acesso aos dados do Google.
• Um complemento é ativado em um documento, formulário, apresentação ou planilha quando alguém o usa.
• Quando as pessoas colaboram em um arquivo e uma delas usa um complemento, ele é instalado para o usuário e ativado para o arquivo.

A tabela a seguir resume as diferenças entre "instalado" e "ativado". Ao testar um script como um complemento, você pode executar o teste em um ou nos dois estados.

	Instalado	Ativado
Aplicável a	Usuário	Documento, formulário, apresentação ou planilha
Causado por	Como comprar um complemento na loja	Adquirir um complemento na loja enquanto usa o documento, formulário, apresentação ou planilha, ou Usar um complemento instalado anteriormente no documento, formulário, apresentação ou planilha
Menu visível para	Somente esse usuário, em todos os documentos, formulários, apresentações ou planilhas que ele abrir ou criar	Todos os colaboradores no documento, formulário, apresentação ou planilha
Modo de autorização para onOpen()	AuthMode.NONE (a menos que também esteja ativado, nesse caso AuthMode.LIMITED)	AuthMode.LIMITED

Modos de autorização

A função onOpen() de um complemento do Editor é executada automaticamente quando um usuário abre um documento, formulário, apresentação ou planilha. Para proteger os dados dos usuários, o Apps Script restringe o que a função onOpen() pode fazer. O estado do complemento do editor determina em qual modo de autorização a função onOpen() é executada.

Se um complemento do Editor estiver ativado no arquivo, formulário, apresentação ou planilha, o onOpen() será executado em AuthMode.LIMITED. Se o complemento não estiver ativado e estiver apenas instalado, o onOpen() será executado em AuthMode.NONE.

No AuthMode.NONE, um complemento não pode executar determinados serviços até que o usuário interaja com ele clicando ou executando funções personalizadas. Se o complemento tentar usar esses serviços em onOpen(), onInstall() ou escopo global, as permissões vão falhar e outras chamadas, como preenchimento de menus, serão interrompidas. A opção "Ajuda" é a única disponível.

Para executar chamadas de serviço restritas, use o modo de autorização AuthMode.FULL. As funções de interação do usuário, como clicar em uma opção de menu, só são executadas nesse modo. Depois que o código é executado no modo AuthMode.FULL, o complemento pode usar todos os escopos autorizados pelo usuário.

Observação: somente complementos do Editor publicados podem estar em AuthMode.NONE; complementos do Editor não publicados são executados onOpen() em AuthMode.LIMITED. No entanto, é possível testar um complemento do Editor para verificar se um complemento em desenvolvimento se comporta conforme o esperado em qualquer modo de autorização.

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.

Os modos de autorização se aplicam a todos os métodos de execução do Apps Script, incluindo a execução no editor de script, em um item de menu ou em uma chamada google.script.run do Apps Script. No entanto, a propriedade e.authMode só pode ser inspecionada se o script for executado como resultado de um gatilho, como onOpen(), onEdit() ou onInstall(). As funções personalizadas das Planilhas Google usam o próprio modo de autorização, AuthMode.CUSTOM_FUNCTION, que é semelhante a LIMITED, mas tem restrições um pouco diferentes. Em todos os outros casos, os scripts são executados em AuthMode.FULL, conforme descrito na tabela a seguir.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Ocorre para	onOpen() (se o usuário tiver instalado um complemento, mas não o tiver ativado no documento, formulário, apresentação ou planilha)	onOpen() (todos os outros horários) onEdit() (somente nas Planilhas)	Funções personalizadas	Em todos os outros momentos, incluindo: acionadores instaláveis onInstall() google.script.run
Acesso aos dados do usuário	Somente local	Somente local	Somente local	Sim
Acesso a documentos, formulários, apresentações ou planilhas	Não	Sim	Sim — somente leitura	Sim
Acesso à interface do usuário	Adicionar itens do cardápio	Adicionar itens do cardápio	Não	Sim
O acesso a Properties	Não	Sim	Sim	Sim
Acesso a Jdbc, UrlFetch	Não	Não	Sim	Sim
Outros serviços	Logger Utilities	Serviços que não acessam dados do usuário	Serviços que não acessam dados do usuário	Todos os serviços

Ciclo de vida de autorização de um complemento do editor

Quando um complemento é instalado para o usuário atual ou ativado no arquivo atual, ele é carregado para o documento, formulário, apresentação ou planilha quando esse arquivo é aberto. O complemento é listado no menu Extensões e começa a detectar os acionadores simples onInstall(), onOpen() e onEdit(). Se um usuário clicar em um item do menu Extensões, ele será executado.

O complemento do Editor está instalado

Quando um complemento do Editor é instalado na loja, a função onInstall() é executada em AuthMode.FULL. Nesse modo de autorização, o complemento pode executar uma rotina de configuração complexa. Você também precisa usar onInstall() para criar itens de menu, já que o documento, o formulário, a apresentação ou a planilha já estão abertos e sua função onOpen() não foi executada. O exemplo a seguir mostra como chamar a função onOpen() na função onInstall():

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

O complemento do Editor é aberto

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

Se um complemento criar apenas um menu básico, o modo não vai importar. A amostra a seguir mostra uma função onOpen() básica:

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

Para adicionar itens de menu dinâmicos com base nas propriedades do Apps Script armazenadas, ler o conteúdo do arquivo atual ou realizar outras tarefas avançadas, você precisa identificar o modo de autorização e processá-lo adequadamente.

O exemplo a seguir mostra uma função onOpen() avançada que muda a ação 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();
}

Aviso: quando a função onOpen() é executada, todo o script é carregado e todas as instruções globais são executadas no mesmo modo de autorização que onOpen(). Se o modo de autorização proibir as instruções globais, tanto as instruções globais quanto onOpen() não serão executadas. Se o complemento publicado não adicionar os itens de menu, revise o console JavaScript do navegador para ver se um erro foi retornado. Em seguida, examine o script para ver se a função onOpen() ou variáveis globais chamam serviços que não são permitidos em AuthMode.NONE.

Os complementos não podem abrir barras laterais ou caixas de diálogo enquanto são executados em AuthMode.LIMITED. Você pode usar itens de menu para abrir barras laterais e caixas de diálogo, já que elas são executadas em AuthMode.FULL.

Um usuário executa o complemento do Editor

Quando um usuário clica em um item do menu Extensões, o Apps Script primeiro verifica se o usuário instalou o complemento e pede que ele faça isso, se necessário. Se o usuário tiver autorizado o complemento, o script vai executar a função que corresponde ao item de menu em AuthMode.FULL. O complemento é ativado no documento, formulário, apresentação ou planilha, se ainda não estiver.

Resolver problemas de renderização dos menus de complementos

O menu de complementos não será renderizado se o código não gerenciar os modos de autorização corretamente. Exemplo:

• Um complemento tenta executar um serviço do Apps Script que não é compatível com o modo de autorização atual.

• Um complemento tenta executar uma chamada de serviço antes que um usuário interaja com ele.

Para remover ou reorganizar uma chamada de serviço que está causando erros de permissão em AuthMode.NONE, tente as seguintes ações:

1. Abra o projeto do Apps Script para seu complemento e localize a função onOpen().
2. Procure na função onOpen() menções a serviços ou objetos do Apps Script associados a eles, como PropertiesService, SpreadsheetApp ou GmailApp.
3. Se um serviço for usado para algo diferente da criação dos elementos da interface, remova-o ou coloque-o em um bloco de comentários. Deixe apenas estes métodos: .getUi(), .createMenu(), .addItem() e .addToUi(). Além disso, encontre e remova qualquer serviço fora de uma função.
4. Identifique as funções que podem conter as linhas de código comentadas ou removidas na etapa anterior, principalmente aquelas que usam as informações produzidas, e mova as chamadas de serviço para as funções que precisam delas. Reorganize ou reescreva sua base de código para acomodar as mudanças feitas nas etapas anteriores.

5. Salve o código e crie uma implantação de teste.

   Ao criar uma implantação de teste, verifique se o campo Configuração está definido como Instalado para o usuário atual e se o texto abaixo da caixa "Configuração" diz Teste em AuthMode.None.

6. Inicie a implantação de teste e abra o menu Extensões.

7. Se todos os itens do menu forem exibidos, o problema estará resolvido. Se você só encontrar o menu Ajuda, volte à etapa 1. Talvez você tenha perdido uma ligação do serviço.

Temas relacionados

• Apps da Web
• Tipos de complementos
• Testar um complemento do Editor