Autorização para serviços do Google

O 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 ou vinculado ao Documentos, Planilhas, Apresentações ou 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 acessar seus arquivos do Google Planilhas ou do Gmail) com base em uma verificação do código. O código comentado ainda pode gerar uma solicitação de autorização. Se um script precisar de autorização, você vai ver uma das caixas de diálogo mostradas aqui 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 página de permissões da sua Conta do Google. Para acessar esta página no futuro, acesse Google.com e clique na foto da sua conta no canto superior direito da tela. Em seguida, clique em Minha conta, depois em Apps e sites conectados na seção "Login e segurança" e em Gerenciar apps.
  2. Clique no nome do script cuja autorização você quer revogar e em Remover à direita. Depois, clique em OK na caixa de diálogo resultante.

Limitar o escopo ao documento atual

Se você estiver criando um complemento ou outro script que use 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 declara @OnlyCurrentDoc, mas o script principal exige acesso a mais do que o arquivo atual.

Ciclo de vida de autorização para complementos

Os complementos dos apps Google 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 que você configura nas configurações dos Serviços 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 vai pedir 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.