Escopos

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

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 uma mensagem de e-mail do usuário ou criar eventos na agenda dele. O projeto de script do complemento define essas permissões individuais como escopos do OAuth.

Os escopos são declarados no manifesto usando strings de URL. Durante o fluxo de autorização, o Apps Script apresenta uma descrição legível do escopo para o usuário. Por exemplo, um complemento do Google Workspace pode usar o escopo "Ler 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 que ele faça o seguinte: Ver suas mensagens de e-mail quando o complemento estiver em execução.

Como acessar escopos

Para conferir os escopos que seu projeto de script exige no momento, faça o seguinte:

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

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

Como definir escopos explícitos

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

Por exemplo, o Apps Script pode conceder 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 do complemento e nada mais.

É possível definir explicitamente os escopos usados pelo projeto de script editando o arquivo manifesto. O campo do manifesto oauthScopes é uma matriz de todos os escopos usados pelo complemento. Para definir os escopos do projeto, faça o seguinte:

1. Confira os escopos que seu complemento usa no momento. 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 ele não estiver presente, adicione-o.

4. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos que seu projeto usa, substitua o conteúdo dessa matriz pelos escopos que você quer que ele 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 OAuth sensíveis pode exigir que seu complemento passe pela verificação do cliente OAuth antes da publicação. Para mais informações, consulte estes guias:

• Verificação de cliente OAuth para o Apps Script
• Apps não verificados
• Perguntas frequentes sobre a verificação do OAuth
• Serviços de APIs do Google: política de dados do usuário

Escopos restritos

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

Confira a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar alguma delas, você precisará obedecer aos Requisitos adicionais para escopos de API específicos antes da publicação.

A extensão Ferramentas para desenvolvedores do Google Workspace para Visual Studio Code fornece informações de diagnóstico para todos os escopos, incluindo a descrição e se ele é sensível ou restrito.

Escolher escopos para complementos do Google Workspace

As seções a seguir fornecem escopos usados com frequência para complementos do Google Workspace.

Escopos de editor

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

Gmail

Alguns escopos foram criados especificamente para Complementos do Google Workspace e ajudar a proteger os dados do Gmail dos usuários. É necessário adicionar esses escopos explicitamente ao manifesto do complemento, junto com outros que o código do complemento exige.

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

Substitua o escopo https://mail.google.com muito amplo no complemento por um conjunto mais restrito de escopos que permitam as interações necessárias e nada mais.

Escopos do Google Agenda

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

Escopos do Google Chat

Para chamar a API Chat, você precisa se autenticar como o usuário do Google Chat ou como o app do Chat. Cada tipo de autenticação exige escopos diferentes, e nem todos os métodos da API Chat são compatíveis com a autenticação de apps.

Para saber mais sobre os escopos do Chat e os tipos de autenticação, consulte a API Chat Visão geral da autenticação e autorização

A tabela a seguir mostra os métodos e escopos da API Chat usados com frequência com base nos tipos de autenticação compatíveis:

Escopos do Google Drive

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

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 receber um token de acesso de um objeto de evento de ação.

A seguir, mostramos um exemplo de como definir um token de acesso para permitir o 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();
}

Outros escopos do Google Workspace

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

A tabela a seguir mostra uma lista de escopos usados com frequência pelos complementos do Google Workspace: