Escopos

Os usuários precisam autorizar complementos e outros aplicativos que acessem os dados ou agir 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, o prompt informa ao usuário o que o aplicativo quer permissão para fazer. Por exemplo, um complemento pode querer permissão para ler um enviar e-mails para um usuário ou criar eventos na agenda. O script do complemento define essas permissões individuais como escopos do OAuth.

Você declara escopos no seu manifesto usando strings de URL. Durante o fluxo de autorização, o Apps Script apresenta uma descrição legível pelo usuário do escopo. Por exemplo, seu complemento do Google Workspace pode usar o erro "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 ao usuário que permita que o complemento acesse suas mensagens de e-mail quando estiver em execução.

Como visualizar escopos

Para conferir 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 info_outline.
3. Confira os escopos em "Escopos do OAuth do projeto".

Também é possível conferir os escopos atuais do projeto de script no manifesto do projeto, no campo oauthScopes, mas somente 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 em busca de chamadas de função que os exigem. Para a maioria dos scripts, isso é suficientes e economiza tempo. No entanto, para complementos publicados, recomendamos controle mais direto dos escopos.

Por exemplo, o Apps Script pode dar a um projeto de script de complemento a opção mais permissiva escopo 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, é obrigatório substituir este escopo por um um conjunto limitado que atenda às necessidades dos complementos e nada mais.

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

1. Veja os escopos usados atualmente pelo complemento. Determine o que mudanças precisam ser feitas, como o uso de um escopo mais restrito.
2. Abra o arquivo de manifesto do complemento.
3. Localize o campo de nível superior rotulado como oauthScopes. Se ele não estiver presente, adicione-o.

4. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos seu projeto usa, substitua o conteúdo dessa matriz pelos escopos que você que quer que ele use. Por exemplo, em 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 o complemento seja aprovado Verificação do cliente OAuth antes de publicá-lo. 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 OAuth
• Serviço 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 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 de ser publicado.

Consulte a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar qualquer uma delas, você precisará obedecer com o Outros requisitos para escopos específicos da API antes da publicação.

Escopos da agenda

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

Escopos do Drive

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

Escopos dos complementos do Gmail

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

Confira abaixo os escopos mais usados 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 estende o Gmail.

Substitua o escopo https://mail.google.com, que é muito amplo, nos seus com um conjunto mais estreito de escopos que permitem as interações necessidades e nada mais.

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.

O exemplo a seguir mostra 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();
}

Escopos de editor

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

Outros escopos

Seu complemento pode exigir escopos adicionais se usar outros serviços do Apps Script. Na maioria dos casos, é possível 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ê esteja substituindo por uma alternativa mais adequada, como um escopo mais estreito.

Como referência, aqui está uma lista de escopos do Apps Script usados com frequência em com complementos do Google Workspace: