Escopos

Os usuários precisam autorizar complementos e outros apps que acessam os dados ou atuam em nome deles. Quando um usuário executa um complemento pela primeira vez, a interface do complemento apresenta uma solicitação de autorização para iniciar o fluxo de autorização.

Durante esse fluxo, a solicitação informa ao usuário o que o aplicativo quer permissão para fazer. Por exemplo, um complemento pode querer permissão para ler a mensagem de e-mail de um usuário ou criar eventos na agenda dele. O projeto de script do complemento define essas permissões individuais como escopos do OAuth.

Declare escopos no seu manifesto usando strings de URL. Durante o fluxo de autorização, o Apps Script apresenta ao usuário uma descrição legível do escopo. Por exemplo, seu complemento do Google Workspace pode usar o escopo "Ler a mensagem atual", que é escrito no manifesto como https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Durante o fluxo de autorização, um complemento com esse escopo pede que o usuário permita o seguinte: Ver suas mensagens de e-mail quando o complemento estiver em execução.

Como visualizar escopos

Para ver os escopos que seu projeto de script exige atualmente, faça o seguinte:

  1. Abra o projeto de script.
  2. À esquerda, clique em Visão geral .
  3. Veja os escopos em "Escopos OAuth do projeto".

Também é possível ver os escopos atuais do projeto de script no manifesto do projeto, no campo oauthScopes, mas somente se você os tiver definido explicitamente.

Definir escopos explícitos

O Apps Script determina automaticamente quais escopos um script precisa, verificando o código em busca de chamadas de função que os exigem. Para a maioria dos scripts, isso é suficiente e economiza tempo, mas para complementos publicados, é necessário ter um controle mais direto dos escopos.

Por exemplo, o Apps Script pode fornecer a um projeto de script de complemento o escopo muito permissivo https://mail.google.com por padrão. Quando um usuário autoriza um projeto de script com esse escopo, o projeto recebe acesso total à conta do Gmail do usuário. Para complementos publicados, você precisa substituir esse escopo por um conjunto mais limitado que atenda às necessidades dos complementos e nada mais.

Para definir explicitamente os escopos usados no projeto de script, edite o arquivo de manifesto. O campo do manifesto oauthScopes é uma matriz de todos os escopos usados pelo complemento. Para definir os escopos do seu projeto, faça o seguinte:

  1. Conferir os escopos usados atualmente pelo complemento. Determine quais mudanças precisam ser feitas, como usar um escopo mais restrito.
  2. Abra o arquivo de manifesto do complemento.
  3. Localize o campo de nível superior chamado oauthScopes. Se não estiver presente, você pode adicioná-lo.

  4. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos usados pelo projeto, substitua o conteúdo dessa matriz pelos escopos que você quer que ela use. Por exemplo, para um complemento do Google Workspace que estende o Gmail, você pode ter o seguinte:

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}

  5. Salve as mudanças no arquivo de manifesto.

Verificação do OAuth

O uso de determinados escopos confidenciais do OAuth pode exigir que o complemento passe pela verificação do cliente OAuth antes da publicação. Para mais informações, consulte estes guias:

Escopos restritos

Alguns escopos são restritos e estão sujeitos a outras regras que ajudam a proteger os dados do usuário. Se você pretende publicar um complemento do Gmail ou do Editor que use um ou mais escopos restritos, o complemento precisa obedecer a todas as restrições especificadas antes de ser publicado.

Consulte a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar algum deles, será necessário estar em conformidade com os Requisitos adicionais para escopos específicos da API antes da publicação.

Escopos do Agenda

Confira abaixo os escopos usados com frequência nos complementos do Google Workspace que estendem o Google Agenda.

Escopo
Acessar metadados de eventos https://www.googleapis.com/auth/calendar.addons.execute

Obrigatório se o complemento acessar metadados de eventos do Google Agenda. Permite que o complemento acesse metadados de eventos.

Ler dados de eventos gerados pelo usuário https://www.googleapis.com/auth/calendar.addons.current.event.read

Obrigatório se o complemento precisar ler dados de eventos gerados pelo usuário. Permite que o complemento acesse dados de eventos gerados pelo usuário. Esses dados só vão estar disponíveis se o campo de manifesto addOns.calendar.eventAccess estiver definido como READ ou READ_WRITE.

Gravar dados de eventos gerados pelo usuário https://www.googleapis.com/auth/calendar.addons.current.event.write

Obrigatório se o complemento precisar gravar dados de eventos gerados pelo usuário. Permite que o complemento edite dados de eventos gerados pelo usuário. Esses dados só vão estar disponíveis se o campo de manifesto addOns.calendar.eventAccess estiver definido como WRITE ou READ_WRITE.

Escopos do Drive

Confira abaixo os escopos usados com frequência para os complementos do Google Workspace que estendem o Google Drive.

Escopo
Ler metadados do item selecionado https://www.googleapis.com/auth/drive.addons.metadata.readonly

Obrigatório se o complemento implementar uma interface contextual acionada quando o usuário selecionar itens no Drive. Permite que o complemento leia metadados limitados sobre itens selecionados por um usuário no Google Drive. Os metadados são limitados ao ID, título, tipo MIME, URL do ícone e se o complemento tem permissão para acessar o item.

Acesso por arquivo https://www.googleapis.com/auth/drive.file

Recomendado se o complemento precisar acessar arquivos individuais do Drive. Concede acesso por arquivo a arquivos criados ou abertos pelo app, usando o serviço avançado do Drive do Apps Script. No entanto, isso não permite o uso de ações semelhantes com o serviço básico do Drive. A autorização de arquivos é concedida por arquivo e é revogada quando o usuário desautoriza o app.

Consulte o exemplo de solicitação de acesso a arquivos selecionados.

Escopos dos complementos do Gmail

Há alguns escopos criados especificamente para complementos do Google Workspace que ajudam a proteger os dados do Gmail dos usuários. É necessário adicionar esses escopos explicitamente ao manifesto do complemento, bem como todos os outros necessários pelo código do complemento.

Confira abaixo os escopos usados com frequência para os complementos do Google Workspace que estendem o Gmail. Aqueles rotulados como Obrigatório precisam ser adicionados ao manifesto dos complementos do Google Workspace se o complemento estender o Gmail.

Lembre-se também de substituir o escopo https://mail.google.com muito amplo no seu complemento por um conjunto mais estreito de escopos que permitem as interações necessárias e nada mais.

Escopo
Criar novos rascunhos https://www.googleapis.com/auth/gmail.addons.current.action.compose

Obrigatório se o complemento usar acionadores de ação de escrita. Permite que o complemento crie temporariamente novos rascunhos de mensagens e respostas. Consulte Como escrever mensagens de rascunho para mais detalhes. Esse escopo também é muito usado com ações de escrita. Requer um token de acesso.

Ler metadados de mensagens abertas https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Concede acesso temporário aos metadados da mensagem aberta, como assunto ou destinatários. Não permite a leitura do conteúdo da mensagem e exige um token de acesso.

Obrigatório se o complemento usar metadados em acionadores de ação de composição. Para ações de composição, esse escopo é necessário se um gatilho de composição precisa acessar metadados. Na prática, esse escopo permite que uma mensagem acione listas de destinatários de acesso (para:, cc: e cco:) de um rascunho de resposta de e-mail.

Ler o conteúdo das mensagens abertas https://www.googleapis.com/auth/gmail.addons.current.message.action

Concede acesso ao conteúdo da mensagem aberta mediante uma interação do usuário, por exemplo, quando um item de menu de complemento é selecionado. Requer um token de acesso.

Ler o conteúdo da conversa aberta https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Concede acesso temporário aos metadados e ao conteúdo da mensagem aberta. Também concede acesso ao conteúdo de outras mensagens na conversa aberta. Requer um token de acesso.

Ler qualquer conteúdo e metadados de mensagens https://www.googleapis.com/auth/gmail.readonly

Ler os metadados e o conteúdo do e-mail, inclusive a mensagem aberta. Obrigatório se você precisar ler informações sobre outras mensagens, como ao conduzir uma consulta de pesquisa ou ler uma conversa inteira de e-mail.

Tokens de acesso

Para proteger os dados do usuário, os escopos do Gmail usados nos complementos do Google Workspace concedem apenas acesso temporário aos dados do usuário. Para ativar o acesso temporário, chame a função GmailApp.setCurrentMessageAccessToken(accessToken) usando um token de acesso como argumento. Você precisa conseguir um token de acesso de um objeto de evento de ação.

Veja a seguir um exemplo de como configurar um token de acesso para permitir acesso aos metadados de uma mensagem. O único escopo necessário para este exemplo é https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Escopos do editor

Confira abaixo os escopos usados com frequência para os complementos do Google Workspace que estendem Documentos, Planilhas e Apresentações.

Escopo
Acesso a arquivos do app Documentos https://www.googleapis.com/auth/documents.currentonly

Obrigatório se o complemento acessar a API Apps Script Docs. Concede acesso temporário ao conteúdo do documento aberto.

Acesso atual aos arquivos do app Planilhas https://www.googleapis.com/auth/spreadsheets.currentonly

Obrigatório se o complemento acessar a API Apps Script Sheets. Concede acesso temporário ao conteúdo da planilha aberta.

Acesso ao arquivo das Apresentações Google https://www.googleapis.com/auth/presentations.currentonly

Obrigatório se o complemento acessar a API Apps Script Slides. Concede acesso temporário ao conteúdo da apresentação aberta.

Acesso por arquivo https://www.googleapis.com/auth/drive.file

Obrigatório para o complemento usar o onFileScopeGrantedTrigger e se ele acessar a API Documentos, Planilhas, Apresentações ou Drive. Concede acesso por arquivo a arquivos criados ou abertos pelo app, usando o serviço avançado do Drive do Apps Script. No entanto, isso não permite o uso de ações semelhantes com o serviço básico do Drive. A autorização é concedida por arquivo e é revogada quando o usuário desautoriza o app.

Outros escopos

Seu complemento pode exigir escopos adicionais se usar outros serviços do Apps Script. Na maioria dos casos, você pode permitir que o Apps Script detecte esses escopos e atualize o manifesto automaticamente. Ao editar a lista de escopos do manifesto, não remova nenhum escopo, a menos que você os esteja substituindo por uma alternativa mais adequada, como um escopo mais restrito.

Veja aqui uma lista de escopos do Apps Script usados com frequência em conjunto com os complementos do Google Workspace:

Escopo
Ler o endereço de e-mail do usuário https://www.googleapis.com/auth/userinfo.email

Permite que o projeto leia o endereço de e-mail do usuário atual.

Permitir chamadas para serviços externos https://www.googleapis.com/auth/script.external_request

Permite que o projeto faça solicitações UrlFetch. Isso também é necessário se o projeto usa a biblioteca OAuth2 para Apps Script.

Ler a localidade e o fuso horário do usuário https://www.googleapis.com/auth/script.locale

Permite que o projeto aprenda a localidade e o fuso horário do usuário atual. Consulte Acessar a localidade e o fuso horário do usuário para ver mais detalhes.

Criar acionadores https://www.googleapis.com/auth/script.scriptapp

Permite que o projeto crie gatilhos.

Visualizar links de terceiros https://www.googleapis.com/auth/workspace.linkpreview

Obrigatório se o complemento visualizar links de um serviço de terceiros. Permite que o projeto acesse um link em um app do Google Workspace enquanto o usuário interage com ele. Para saber mais, consulte Visualizar links com ícones inteligentes.

Criar recursos de terceiros https://www.googleapis.com/auth/workspace.linkcreate

Obrigatório se o complemento criar recursos em um serviço de terceiros. Permite que o projeto leia as informações enviadas pelos usuários ao formulário de criação de recursos e insira um link para o recurso em um aplicativo do Google Workspace. Para saber mais, consulte Criar recursos de terceiros no menu @.