Autorização do complemento do editor

A autorização para muitos apps baseados no Apps Script é simples, porque o projeto de script solicita as permissões ausentes 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 que ele instala 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 nos 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 o 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 Extensions estão instalados, ativados ou ambos.

• Um complemento é instalado para um usuário específico depois que ele ou o administrador o obtém no 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, é possível executar o teste em um ou ambos esses 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, 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.

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 vão falhar, e outras chamadas, como preenchimento de menus, vão parar. A ajuda é a única opção 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ão executadas somente nesse modo. Depois que o código for executado no modo AuthMode.FULL, o complemento poderá usar todos os escopos que o usuário autorizou.

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 no tipo enumerado 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 nas 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.

Ciclo de vida da 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 de menu de 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. Também é necessário 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 é 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 se um complemento está 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 em propriedades do Apps Script armazenadas, para ler o conteúdo do arquivo atual ou para 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();
}

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 verifica primeiro se o usuário instalou o complemento e solicita que ele faça isso se não tiver feito. 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 estava.

Resolver problemas de menus de complementos que não são renderizados

O menu do complemento pode 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 estas ações:

1. Abra o projeto do Apps Script para seu complemento e localize a função onOpen().
2. Pesquise na função onOpen() 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 qualquer coisa que não seja a criação de elementos da interface, remova-o ou envolva-o em um bloco de comentários. Deixe apenas estes métodos: .getUi(), .createMenu(), .addItem() e .addToUi(). Encontre e remova 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 que elas produzem, 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 Config está Installed for current user e se o texto abaixo da caixa Config diz Test in 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 foi corrigido. Se você só encontrar o menu Help, volte para a etapa 1. Talvez você tenha perdido uma chamada de serviço.

Temas relacionados

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