Autorização para serviços do Google

O Google Apps Script exige autorização do usuário para acessar dados particulares de serviços integrados do Google ou serviços avançados do Google.

Como funciona a autorização para os Serviços do Google

Quando um script precisa acessar os serviços do Google, ele segue este processo geral:

  1. Detecção: o Apps Script verifica o script para identificar quais serviços ele usa (por exemplo, SpreadsheetApp ou GmailApp).
  2. Determinação do escopo: com base na verificação, o Apps Script identifica um conjunto de escopos do OAuth necessários para a execução do script.
  3. Verificação de autorização: quando o script é executado, ele verifica se o usuário já autorizou esses escopos.
  4. Solicitação do usuário: se a autorização estiver faltando, uma caixa de diálogo vai aparecer pedindo que o usuário conceda permissão.
  5. Execução: depois que o script é autorizado, ele pode acessar os dados solicitados para esse usuário.

Permissões e tipos de scripts

A identidade do usuário com que um script é executado e, portanto, os dados que ele pode acessar variam de acordo com o cenário em que o script é executado, conforme mostrado na tabela a seguir.

Tipo de script O script é executado como...
Autônomo, complemento do Google Workspace ou vinculado ao Google Docs, Google Planilhas, Google Apresentações ou Google Formulários Usuário no teclado
Função personalizada em uma planilha Usuário anônimo; no entanto, os limites de cota contam para o usuário no teclado
Web app ou Gadget do Google Sites Usuário no teclado ou proprietário do script, dependendo das opções selecionadas ao implantar o app
Gatilho instalável Usuário que criou o gatilho

Conceder direitos de acesso

O Apps Script determina automaticamente os escopos de autorização (como acesso aos arquivos das Planilhas ou ao Gmail) com base em uma verificação do código. O código que está comentado ainda pode gerar uma solicitação de autorização. Se um script precisar de autorização, uma caixa de diálogo vai aparecer quando ele for executado.

Os scripts que você autorizou anteriormente também pedem autorização adicional se uma mudança de código adicionar novos serviços. Os scripts não podem solicitar autorização se você acessar o script como um app da Web que é executado com a identidade de usuário do proprietário do script.

Revogar direitos de acesso

Para revogar o acesso de um script aos seus dados, siga estas etapas:

  1. Acesse a seção "Segurança" da sua Conta do Google.
  2. Em Suas conexões com apps e serviços de terceiros, clique em Ver todas as conexões.
  3. Selecione o script ou app de que você quer revogar o acesso.
  4. Clique em Excluir todas as conexões com APP_NAME e em Confirmar.

Limitar o escopo ao documento atual

Se você estiver criando um complemento ou outro script que usa o serviço de planilhas, serviço de documentos, serviço de apresentações ou serviço de formulários, é possível forçar a caixa de diálogo de autorização a pedir acesso apenas aos arquivos em que o complemento ou script é usado, em vez de todas as planilhas, documentos ou formulários de um usuário. Para isso, inclua a seguinte anotação JSDoc em um comentário no nível do arquivo:

/**
 * @OnlyCurrentDoc
 */

Uma anotação oposta, @NotOnlyCurrentDoc, está disponível se o script incluir uma biblioteca que declare @OnlyCurrentDoc, mas o script principal exija acesso a mais do que o arquivo atual.

Ciclo de vida de autorização para complementos

Os complementos do Planilhas, Documentos, Apresentações e Formulários geralmente seguem o mesmo modelo de autorização dos scripts vinculados a um documento. Em determinadas circunstâncias, no entanto, as funções onOpen(e) e onEdit(e) são executadas em um modo sem autorização que apresenta algumas complicações adicionais. Para mais informações, consulte o guia sobre o ciclo de vida da autorização de complementos.

Limites de usuários do aplicativo OAuth

Os aplicativos que usam o OAuth para acessar dados de usuários do Google, incluindo projetos do Apps Script, estão sujeitos a limites de autorização. Consulte Limites de usuários de aplicativos OAuth para mais detalhes.

Comportamento de reautenticação com o Apps Script

O Apps Script não aplica a frequência de reautenticação configurada nas configurações de serviço do Google Cloud. Isso acontece porque o Apps Script pode ser executado automaticamente usando gatilhos, que funcionam sem interação direta do usuário. Essas execuções automatizadas não acionam os avisos de reautenticação. O aplicativo do Apps Script não pede automaticamente que você faça uma nova autenticação após o período especificado (por exemplo, 12 horas).

Definir escopos explícitos no manifesto

O Apps Script determina automaticamente os escopos necessários ao analisar o código em busca de chamadas de função. Se você precisar de mais controle, defina explicitamente os escopos no manifesto do projeto (appsscript.json). Isso é recomendado para scripts publicados para garantir que você esteja usando as permissões mínimas necessárias.

Para instruções, consulte Definir escopos explícitos.

Solução de problemas

  • Erro"Autorização necessária" ao executar um gatilho: os gatilhos precisam ser autorizados pelo usuário que os criou. Se você adicionar um código que exija novas permissões, execute manualmente uma função no editor de scripts uma vez para acionar a caixa de diálogo de autorização.
  • Escopos não estão sendo atualizados: se você atualizou o código, mas a caixa de diálogo de autorização não reflete as mudanças, tente salvar o projeto e atualizar o editor. Se você estiver usando escopos explícitos no manifesto, verifique se adicionou o novo escopo à matriz oauthScopes.
  • "Este app está bloqueado" ou aviso de app não verificado: isso ocorre se o script usa escopos sensíveis ou restritos e não foi verificado pelo Google. Consulte Verificação do cliente OAuth.