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 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. Os colaboradores que não precisam 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. O 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, comoPropertiesService
,SpreadsheetApp
ouGmailApp
. - 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.