Na maioria dos casos, você precisa autorizar um complemento antes de usá-lo. Para muitos projetos do Apps Script, como os apps da Web, a autorização é simples: o projeto de script pede todas as permissões necessárias quando você tenta usá-lo. Depois de autorizado, você poderá usar o projeto de script livremente. Todos que usam o projeto de script o autorizam separadamente.
O modelo de autorização dos Complementos de editor é mais complexo. Como esses complementos funcionam em arquivos que residem no Google Drive (arquivos que podem ser compartilhados com outros), você precisa criar complementos de editor com os diferentes modos de autorização em mente. Os aplicativos do editor do Google Workspace também oferecem um menu Complementos na IU, que é preenchido pelos complementos instalados, mesmo que você ainda não tenha autorizado esses complementos. Isso aumenta a complexidade do modelo de autorização.
Modelo de autorização
Duas propriedades dos complementos do Editor facilitam o compartilhamento e o uso:
- Depois de instalar um complemento do Editor na loja, você o verá no menu de complementos de cada documento aberto ou criado. Os colaboradores nesses documentos não verão o complemento, exceto nos documentos em que você realmente o utiliza.
- Quando você usa um complemento do Editor em um documento, seus colaboradores também o veem no menu de complementos, mas apenas para esse documento, a menos que também tenham instalado esse complemento.
Esse modelo de compartilhamento é natural para a maioria dos usuários. No entanto, como um complemento
do editor executa automaticamente a função onOpen(e)
para adicionar itens de menu quando um
documento é aberto, o comportamento acima adiciona alguma complexidade às regras de autorização
do Apps Script. Afinal, os usuários não ficariam à vontade com um
complemento que acessa dados pessoais toda vez que abrem um documento. Este guia
ajudará você a entender o que seu código pode fazer e quando.
Instalado x ativado
Se você vir um complemento do editor no menu, ele está em um (ou ambos) dois estados: instalado e ativado. Um complemento do Editor é instalado para um usuário específico depois que ele escolhe o complemento na loja e o autoriza a acessar os dados do Google. Por outro lado, um complemento é ativado em um determinado documento quando alguém o usa. Se duas pessoas colaborarem em um documento e uma delas usar um complemento, ele será instalado para o usuário e ativado para o documento.
A tabela abaixo resume os dois estados. Observe que, ao testar um script como complemento, você pode optar por executar o teste em um ou ambos os estados.
Instalado | Ativado | |
---|---|---|
Válido para | Usuário | Documentos |
Causado por | Como instalar um complemento na loja | Instalar um complemento da loja ao usar o documento ou Usar um complemento já instalado no documento |
Menu visível para | Somente esse usuário, em todos os documentos que ele abre ou cria | Todos os colaboradores do documento |
onOpen(e) corridas em |
AuthMode.NONE (a menos que também esteja ativado, caso em que AuthMode.LIMITED)
|
AuthMode.LIMITED |
Modos de autorização
Um complemento do Editor executa automaticamente a função onOpen(e)
para adicionar itens de menu
quando um documento é aberto, mas para proteger os dados dos usuários, o Apps Script restringe
o que a função onOpen(e)
pode fazer. Se o complemento não tiver sido usado no
documento atual, essas restrições ficarão mais graves.
Especificamente, os estados de instalação e ativação determinam em qual modo de autorização a função onOpen(e)
é executada. O Apps Script transmite o modo de autorização
como a propriedade authMode
do
parâmetro de evento e
, o valor de e.authMode
corresponde a uma constante na enumeração
ScriptApp.AuthMode
do Apps Script.
Se um complemento do Editor estiver ativado no documento atual, o onOpen(e)
será executado em
AuthMode.LIMITED
. Se o complemento não estiver ativado e estiver instalado apenas,
onOpen(e)
será executado em AuthMode.NONE
.
O conceito de modos de autorização se aplica a todas as execuções do Apps Script, como a execução no editor de script, em um item de menu ou em uma chamada google.script.run
do Apps Script, embora a propriedade e.authMode
só possa ser inspecionada se o script for executado como resultado de um gatilho como onOpen(e)
, onEdit(e)
ou onInstall(e)
. As 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 um pouco diferentes. O
tempo restante, os scripts são executados em AuthMode.FULL
, conforme detalhado na tabela
abaixo.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Isso ocorre durante | onOpen(e) se o usuário tiver instalado um complemento, mas não o tiver ativado no documento |
onOpen(e) (todos os outros horários)onEdit(e) (somente no Planilhas) |
Funções personalizadas | Todos os outros momentos, incluindo: acionadores instaláveis onInstall(e) google.script.run |
Acesso aos dados do usuário | Somente localidade | Somente localidade | Somente localidade | Sim |
Acesso ao documento | Não | Sim | Sim (somente leitura) | Sim |
Acesso à interface do usuário | Adicionar itens de cardápio | Adicionar itens de cardápio | Não | Sim |
O acesso a Properties |
Não | Sim | Yes | Sim |
Acesso a Jdbc , UrlFetch |
Não | Não | Sim | Sim |
Outros serviços | Logger Utilities |
Serviços que não acessam os dados do usuário | Serviços que não acessam os dados do usuário | Todos os serviços |
O ciclo de vida completo
Se um complemento foi instalado para o usuário atual ou ativado no documento
atual, o complemento é carregado no documento, o que faz com que ele apareça
no menu de complementos e comece a detectar os
acionadores simples onInstall(e)
,
onOpen(e)
e onEdit(e)
. Se um usuário clicar em um dos itens de menu do complemento,
ele será executado.
Instalando
Quando um complemento do Editor é instalado a partir da loja, a função onInstall(e)
é executada em AuthMode.FULL
. Isso permite que o complemento execute uma rotina de configuração complexa,
mas é importante também usar a onInstall(e)
para criar itens de menu, já que o
documento já está aberto e, portanto, sua função onOpen(e)
não foi executada. Por conveniência, chame onOpen(e)
a partir de onInstall(e)
, conforme mostrado neste exemplo:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
Abertura
Quando um documento é aberto, ele carrega cada complemento do editor que o usuário atual instalou ou que qualquer colaborador tenha ativado no documento e chama cada uma das funções onOpen(e)
. O modo de autorização no qual o onOpen(e)
é executado
depende se um complemento está instalado ou ativado.
Se um complemento cria apenas um menu básico, o modo não importa. Este exemplo
mostra como seria um onOpen(e)
simples:
function onOpen(e) {
SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
.addItem('Insert chart', 'insertChart')
.addItem('Update charts', 'updateCharts')
.addToUi();
}
No entanto, se você quiser adicionar itens de menu dinâmicos com base nas propriedades armazenadas do Apps Script, ler o conteúdo do documento atual ou executar outras tarefas avançadas, precisará detectar o modo de autorização e processá-lo corretamente. Este exemplo mostra como pode ser uma função onOpen(e)
avançada, mudando o comportamento dela 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();
}
Em execução
Quando alguém clica em um dos itens de menu de um complemento, o Apps Script primeiro verifica se o usuário instalou o complemento e solicita que ele faça isso.
Se o usuário tiver autorizado o complemento, o script executará a função que
corresponde ao item de menu em AuthMode.FULL
. O complemento também é ativado no documento, caso ainda não tenha sido.