Esta página foi traduzida pela API Cloud Translation.

Autorização do complemento do editor

A autorização para muitos apps baseados no Apps Script é simples porque projeto de script solicita as permissões necessárias quando alguém tenta para 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 instalados por ele estão listados no menu Extensões, mesmo caso o usuário ainda não tenha autorizado esses complementos.
Esses complementos funcionam em arquivos do Google Drive que pode ser compartilhado com os colaboradores. Colaboradores que não tem o complemento Editor instalado vê-lo nos documentos onde o criador 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 instalado, ativado ou ambos.

Um complemento está instalado para uma determinada usuário depois que ele ou o administrador o receberem no Google Workspace Marketplace e autorizar 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 um delas usa um ele será instalado para o usuário e enabled 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	Obter um complemento da loja durante o uso documento, formulário, apresentação ou planilha, ou Usar um complemento já instalado 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 a privacidade dos usuários, dados, o Apps Script restringe o que os onOpen() pode fazer. Estado do complemento 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.

No AuthMode.NONE, não é possível executar um complemento com determinada serviços até que o usuário interaja com o complemento pela clicar ou executar funções personalizadas. Se as o complemento tenta usar esses serviços em onOpen(), onInstall() ou de escopo global, falhas nas permissões e outras chamadas, como preencher cardápios, parar. "Ajuda" é a única opção compatível.

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

O Apps Script passa no modo de autorização como a propriedade authMode do Apps Script. parâmetro de evento, e o valor de e.authMode corresponde a uma constante no Apps Script. Enumeração ScriptApp.AuthMode.

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ó poderá ser inspecionada se o script for executado como resultado. de um acionador, como onOpen(), onEdit() ou onInstall(). 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 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 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 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 os dados do usuário	Qualquer serviço que não acesse os 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 ativada no arquivo atual, a for carregado para o documento, formulário, apresentação ou planilha quando o arquivo for aberto. O complemento é listadas no menu Extensões e começa a ouvir os acionadores simples onInstall(), onOpen() e onEdit(). Se um usuário clicar Extensões, ele será executado.

O complemento 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 Editor está 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 que onOpen() em execução depende do fato 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();
}

Adicionar itens de menu dinâmicos com base no Apps Script armazenado. properties, para ler o conteúdo do arquivo atual, ou para 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 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: Você pode usar itens de menu para abrir barras laterais e caixas de diálogo, já que elas são executadas no AuthMode.FULL.

Um usuário executa o complemento Editor

Quando um usuário clica em um item de menu Extensões, Primeiro, o Apps Script verifica se o usuário instalou o e caso contrário. Se o usuário autorizou a o script executa a função que corresponde ao item de menu em AuthMode.FULL. A está ativado nos formatos de documento, formulário apresentação ou planilha, se ainda não tiver feito.

Resolver problemas de menus de complementos que não estão sendo 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 o Apps Script que não tem suporte no modo de autorização atual.
Um complemento tenta executar uma chamada de serviço antes de um usuário interagir com ele.

Para remover ou reorganizar uma chamada de serviço que está causando erros de permissão em AuthMode.NONE, tente fazer o seguinte:

Abra o projeto do Apps Script para seu complemento e localize a função onOpen().
Pesquisar menções ao Apps Script na função onOpen() serviços ou objetos associados a elas, como PropertiesService, SpreadsheetApp ou GmailApp.
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(). Além disso, encontre e remova qualquer serviço que esteja fora de uma função.
Identificar funções que podem conter as linhas de código comentadas ou removidas na etapa anterior, especialmente aqueles que usam as informações que eles produzem, e mover 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.
Salve o código e crie uma implantação de teste.

Ao criar uma implantação de teste, verifique se o campo Config é Instalado para o usuário atual e que o texto abaixo da caixa de configuração diz Teste em AuthMode.None
Inicie a implantação de teste e abra o menu Extensões.
Se todos os itens de menu forem exibidos, o problema foi corrigido. Se você vir apenas o menu Ajuda, volte para a etapa 1. Talvez você tenha perdido uma chamada de serviço.