Autorização do complemento do editor

A autorização para muitos apps do Google Apps Script é simples. O projeto de script solicita as permissões necessárias ausentes 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 são listados no menu Extensões, mesmo que o usuário ainda não tenha autorizado esses complementos.

• Esses complementos funcionam em arquivos do Google Drive que podem ser compartilhados com colaboradores. Os colaboradores que não têm o complemento do editor instalado o veem 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, os modos de autorização são aplicados para tornar alguns serviços indisponíveis para onOpen. Este guia explica 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 são instalados, ativados ou ambos:

• Um complemento é instalado para um determinado usuário depois que ele ou o administrador o recebe do Google Workspace Marketplace e o autoriza a acessar os 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 esse 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 ambos os estados.

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, onOpen será executado em AuthMode.LIMITED. Se o complemento não estiver ativado e for apenas instalado, onOpen será executado em AuthMode.NONE.

Em 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 falharão e outras chamadas, como o preenchimento de menus, serão interrompidas. A ajuda é a única opção compatí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ão executadas apenas nesse modo. Depois que o código é executado no modo AuthMode.FULL, o complemento pode usar todos os escopos autorizados.

Somente os complementos do editor publicados podem estar em AuthMode.NONE; os complementos do editor não publicados executam onOpen em AuthMode.LIMITED. No entanto, pretendido em qualquer modo de autorização. Para fazer isso, teste um complemento do editor.

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 scripts, em um item de menu ou em uma chamada do Apps Script google.script.run. No entanto, a propriedade e.authMode só pode ser inspecionada se o script for executado como resultado de um acionador como onOpen, onEdit ou onInstall. 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 ligeiramente diferentes. Para todos os outros casos, os scripts são executados em AuthMode.FULL, conforme descrito na tabela a seguir.

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 ouvir os acionadores simples onInstall, onOpen, e onEdit. Se um usuário clicar em um item de 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, formulário, apresentação ou planilha já está aberto e a função onOpen não foi executada. O exemplo a seguir mostra como chamar a função onOpen da função onInstall:

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

O complemento do editor está 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 qualquer colaborador ativou no arquivo e chama cada uma das funções onOpen. O modo de autorização em que onOpen é executado depende de um complemento instalado ou ativado.

Se um complemento criar apenas um menu básico, o modo não importa. O exemplo 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 armazenadas do Apps Script properties, ler o conteúdo do arquivo atual ou realizar outras tarefas avançadas, é necessário 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();
}

Quando a função onOpen é executada, todo o script é carregado e 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, as instruções globais e onOpen não serão executadas. Se o complemento publicado não conseguir adicionar os itens de menu, revise o console do navegador para conferir se um erro foi retornado. Em seguida, examine o script para conferir se a função onOpen ou as 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 durante a execução em AuthMode.LIMITED. É possível 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 de menu Extensões , o Apps Script primeiro verifica se o usuário instalou o complemento e solicita que ele faça isso, se não. Se o usuário autorizou o complemento, o script executa 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 menus de complementos que não estão sendo renderizados

O menu de complementos pode não ser renderizado se o código não gerenciar os modos de autorização corretamente. Por 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. Pesquise a função onOpen para menções de 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. Encontre e remova também qualquer serviço que esteja 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 a 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á Instalado para o usuário atual e se o texto abaixo da caixa de 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 de menu forem exibidos, o problema será corrigido. Se você só vir o menu Ajuda, volte à etapa 1. Talvez você tenha perdido uma chamada de serviço.

Temas relacionados

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