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 Os Complementos do Editor são 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 se o usuário ainda não tiver autorizado esses complementos.

  • Esses complementos funcionam em arquivos do Google Drive que pode ser compartilhado com os 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 o 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ível para onOpen(). Este guia pode ajudar você a entender qual código pode fazer e quando.

Modelo de autorização

O modo de autorização de um complemento do Editor depende seu estado, que depende de quem o está usando: o usuário que instalou o complemento ou 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 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 está ativado em um documento, formulário apresentação ou planilha quando alguém os utilizar lá.
  • 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 a versão instalada e a ativada. Quando você testar um script como complemento é possível executar o teste em um ou ambos os estados.

Instalado Ativado
Aplicável a Usuário Documento, formulário, apresentação ou planilha
Causado por Comprar um complemento da loja Receber um complemento da loja enquanto usa esse documento, formulário, apresentação ou planilha ou
Usar um complemento instalado anteriormente nesse 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 abrem ou criam Todos os colaboradores do documento, formulário, apresentação ou planilha
Modo de autorização para onOpen()
de 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, onOpen() é executado AuthMode.LIMITED. Se o complemento não estiver ativado instalado, o onOpen() é 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 restrito, use a autorização AuthMode.FULL modo 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 é executado no modo AuthMode.FULL, o complemento pode 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 um script do Google Apps chamada google.script.run. 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. Para todos Em outros casos, os scripts serão executados em AuthMode.FULL, conforme descrito abaixo. tabela.

NONE LIMITED CUSTOM_FUNCTION FULL
Ocorre para onOpen() (se o usuário tiver instalado um um complemento, mas não o ativou no apresentação ou planilha) onOpen() (todos os outros horários)
onEdit() (somente nas Planilhas)		 Funções personalizadas Todas as outras vezes, incluindo:
acionadores instaláveis
onInstall()
google.script.run
Acesso aos dados do usuário Somente localidade Somente localidade Somente localidade 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		 Qualquer serviço que não acesse dados do usuário Qualquer serviço que não acesse os dados do usuário Todos os serviços

Ciclo de vida da autorização de um complemento do Editor

Quando um complemento é instalado para o usuário atual ou ativada no arquivo atual, a for carregado para o documento, formulário, apresentação ou planilha quando o arquivo for 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 Extensões, ele será executado.

O complemento do editor está instalado

Quando um Complemento do Editor é instalado da Chrome Web Store, A função onInstall() é executada em AuthMode.FULL. Neste modo de autorização, a do Google Cloud pode executar uma rotina de configuração complexa. Você também deve use onInstall() para criar itens de menu, já que o documento, o formulário, a apresentação ou planilha já está aberta e sua 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 todas as Complemento do editor instalado pelo usuário atual 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 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();
}

Observe que os complementos não podem abrir barras laterais ou caixas de diálogo enquanto são executados no 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 tiver feito. Se o usuário autorizou a o script executa a função que corresponde ao item de menu em AuthMode.FULL. O está ativado nos formatos de documento, formulário apresentação ou planilha, se ainda não tiver feito.

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

O menu do complemento pode não ser renderizado se o código não gerencia 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 algo que não seja a criação dos elementos da interface, removê-la ou envolvê-la 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. Reorganizar ou reescrever 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 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 de 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.