Esta página foi traduzida pela API Cloud Translation.

Autorização de complementos 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 instalados pelo usuário são listados no menu Extensões, mesmo que o usuário ainda não tenha autorizado esses complementos.
Esses complementos funcionam em arquivos no Google Drive que podem ser compartilhados com colaboradores. Os colaboradores que não têm o complemento do Editor instalado podem vê-lo 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 seu código pode fazer e quando.

Modelo de autorização

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

Estados dos complementos do editor

os complementos do Editor no menu Extensões sejam instalados, ativados ou ambos.

Um complemento é instalado para um usuário específico depois que ele ou o administrador o instala no 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 usado por alguém.
Quando as pessoas colaboram em um arquivo e uma delas usar um complemento, ele é instalado para o usuário e ativado para o arquivo.

A tabela a seguir resume as diferenças entre instalados e ativados. Quando você testa um script como um complemento, é possível executar o teste em um desses estados ou em ambos.

	Instalado	Ativado
Válido para	Usuário	Documento, formulário, apresentação ou planilha
Causado por	Como adquirir um complemento da loja	Comprar um complemento da loja ao usar 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 ele abrir ou criar;	Todos os colaboradores do documento, formulário, apresentação ou planilha
Modo de autorização para `onOpen()`	`AuthMode.NONE` (a menos que também esteja ativada). 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() será 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 só estiver 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 o complemento clicando ou executando funções personalizadas. Se o complemento tentar usar esses serviços em onOpen(), onInstall() ou no escopo global, as permissões vão falhar e outras chamadas, como preencher menus, serão interrompidas. Ajuda é a única opção disponível.

Para executar chamadas de serviço restritas, é preciso usar 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 pelo usuário.

O Apps Script transmite o modo de autorização como a propriedade authMode do parâmetro de evento e do Apps Script. 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 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 acionador, 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 ao LIMITED, mas tem restrições um pouco diferentes. Para todos os outros casos, os scripts são executados em AuthMode.FULL, conforme descrito na tabela a seguir.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Ocorre por	`onOpen()` (se o usuário instalou um complemento, mas não o ativou no documento, formulário, apresentação ou planilha)	`onOpen()` (todos os outros horários) `onEdit()` (somente no Planilhas)	Funções personalizadas	Todos os outros horários, incluindo: gatilhos instaláveis `onInstall()` `google.script.run`
Acesso aos dados do usuário	Somente localidade	Somente localidade	Somente localidade	Sim
Acesso a um documento, formulário, apresentação ou planilha	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	Yes	Sim
Acesso a `Jdbc` e `UrlFetch`	Não	Não	Sim	Sim
Outros serviços	`Logger` `Utilities`	Todos os serviços que não acessam os dados do usuário	Todos os serviços que não acessam os dados do usuário	Todos os serviços

Ciclo de vida da autorização de um complemento de 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 o arquivo é aberto. O complemento é listado no menu Extensões e começa a detectar gatilhos 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 pela loja, a função onInstall() dele é 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() a partir 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 instalados pelo usuário atual ou que qualquer colaborador ativou no arquivo e chama cada uma das funções onOpen() dele. O modo de autorização em que o onOpen() é executado depende de um complemento estar 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 dinâmicos de menu com base nas propriedades armazenadas do Apps Script, ler o conteúdo do arquivo atual ou executar 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. 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 de menu Extensões, o Apps Script verifica primeiro se o usuário instalou o complemento e, caso contrário, solicita que ele faça isso. Se o usuário autorizou o complemento, o script vai executar a função que corresponde ao item de menu em AuthMode.FULL. O complemento será ativado no documento, formulário, apresentação ou planilha, se ainda não estiver.

Resolver problemas de renderização de menus de complementos

O menu do complemento 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:

Abra o projeto do Apps Script do complemento e localize a função onOpen().
Pesquise na função onOpen() menções a serviços ou objetos do Apps Script associados a eles, como PropertiesService, SpreadsheetApp ou GmailApp.
Se um serviço for usado para algo que não seja a criação de elementos da IU, 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 que esteja fora de uma função.
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 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.
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 mostra Testar em AuthMode.None.
Inicie a implantação de teste e abra o menu Extensions.
Se todos os itens de menu forem exibidos, o problema foi corrigido. Se apenas o menu Ajuda aparecer, volte para a etapa 1. Talvez você tenha perdido uma chamada de serviço.