Escopos

Os usuários precisam autorizar complementos e outros aplicativos que acessam os dados ou agem 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 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.

Você declara escopos no manifest 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, o complemento do Google Workspace pode usar o escopo "Ler mensagem atual", que é gravado 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 o complemento acesse suas mensagens de e-mail quando estiver em execução.

Observação: os escopos que o Apps Script usa para os vários serviços se sobrepõem aos escopos usados pela API relacionada. Por exemplo, o serviço de agenda do Apps Script usa muitos dos mesmos escopos da API Calendar. É possível consultar os escopos que métodos de serviço específicos do Apps Script exigem na documentação de referência do Apps Script.

Como conferir 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 .
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 é suficiente e economiza tempo, mas para complementos publicados, é necessário exercer um controle mais direto dos escopos.

Por exemplo, o Apps Script pode conceder a um projeto de script complementar o escopo https://mail.google.com muito permissivo 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, é necessário substituir esse escopo por um conjunto mais limitado que atenda às necessidades dos complementos.

Aviso: sempre use o conjunto de escopo menos permissivo possível. Para proteger as informações do usuário, os complementos e outros aplicativos publicados nunca devem solicitar mais permissões de escopo do que o necessário. Os escopos necessários para o complemento são examinados durante o processo de análise do complemento de publicação. Se o complemento usar escopos muito amplos, ele não poderá ser aprovado.

É possível definir explicitamente os escopos usados pelo projeto de script editando o arquivo manifest. O campo de 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 usados pelo complemento. Determine quais mudanças precisam ser feitas, como usar um escopo mais estreito.
2. Abra o arquivo de manifesto do complemento.
3. Localize o campo de nível superior com a etiqueta oauthScopes. Se ele não estiver presente, adicione-o.

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 usar. 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 sensíveis do OAuth pode exigir que seu complemento passe por uma verificação de cliente do 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ç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 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 de ser publicado.

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

Observação: evite usar escopos restritos no seu complemento, se possível. É mais fácil passar na análise de complementos para publicação pública se você não os usar. É possível usar escopos restritos livremente para complementos não públicos.

Escolher escopos para complementos do Google Workspace

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

Escopos de editor

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

Observação:o escopo currentonly só está disponível nos serviços do Apps Script. Isso não inclui os Advanced Services do Apps Script ou chamadas diretas para as APIs do Google Workspace.

Escopo
Acesso atual a arquivos do Documentos	https://www.googleapis.com/auth/documents.currentonly Obrigatório se o complemento acessar a API Docs do Apps Script. Concede acesso temporário ao conteúdo do documento aberto.
Acesso ao arquivo atual das Páginas	https://www.googleapis.com/auth/spreadsheets.currentonly Obrigatório se o complemento acessar a API Sheets do Apps Script. Concede acesso temporário ao conteúdo da planilha aberta.
Acesso ao arquivo atual do Apresentações Google	https://www.googleapis.com/auth/presentations.currentonly Obrigatório se o complemento acessar a API Slides do Apps Script. Concede acesso temporário ao conteúdo da apresentação aberta.
Acesso por arquivo	https://www.googleapis.com/auth/drive.file O complemento precisa usar o onFileScopeGrantedTrigger e 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 Google Drive do Apps Script. No entanto, isso não permite o uso de ações semelhantes usando o serviço básico do Drive. A autorização de arquivo é concedida por arquivo e é revogada quando o usuário desautoriza o app.

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 também o escopo https://mail.google.com muito amplo no seu complemento por um conjunto mais restrito de escopos que permitam as interações necessárias para o complemento.

Escopo
Criar novos rascunhos	https://www.googleapis.com/auth/gmail.addons.current.action.compose Obrigatório se o complemento usa acionadores de ação de composição. Permite que o complemento crie temporariamente novas mensagens de rascunho e respostas. Consulte Como criar rascunhos de mensagens para mais detalhes. Esse escopo também é usado com frequência com ações de composição. 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 o assunto ou os destinatários). Não permite a leitura do conteúdo da mensagem e exige um token de acesso. Obrigatório se o complemento usa metadados em gatilhos de ação de composição. Para ações de composição, esse escopo é necessário se um acionador de composição precisar de acesso a metadados. Na prática, esse escopo permite que um gatilho de composição ative listas de destinatários (para:, cc: e bcc:) de um rascunho de e-mail de resposta.
Ler o conteúdo da mensagem aberta	https://www.googleapis.com/auth/gmail.addons.current.message.action Concede acesso ao conteúdo da mensagem aberta após uma interação do usuário, como 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 da mensagem	https://www.googleapis.com/auth/gmail.readonly Ler os metadados e o conteúdo de qualquer e-mail, incluindo a mensagem aberta. Obrigatório se você precisar ler informações sobre outras mensagens, por exemplo, ao realizar uma consulta de pesquisa ou ler uma conversa inteira. Aviso: esse é um escopo restrito muito amplo. Use apenas se for absolutamente necessário.

Escopos do Google Agenda

Confira abaixo os escopos mais usados para 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 da Agenda. Permite que o complemento acesse os metadados do evento.
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ó estão 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ó estão disponíveis se o campo de manifesto addOns.calendar.eventAccess estiver definido como WRITE ou READ_WRITE.

Escopos do Google Chat

Prévia para desenvolvedores:disponível como parte do Programa de prévia para desenvolvedores do Google Workspace, que concede acesso antecipado a determinados recursos.

Para chamar a API Chat, você precisa fazer a autenticação como o usuário do Google Chat ou como o app do Chat. Cada tipo de autenticação requer escopos diferentes, e nem todos os métodos da API Chat oferecem suporte à autenticação de apps.

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

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

Método	Compatível com autenticação do usuário	Suporte a autenticação de apps	Escopos de autorização compatíveis
Enviar uma mensagem			Com a Autenticação do usuário: chat.messages.create chat.messages chat.import Com a autenticação de app: chat.bot
Criar um espaço			Com a Autenticação do usuário: chat.spaces.create chat.spaces chat.import Com a autenticação de apps e a aprovação do administrador (disponível na prévia para desenvolvedores): chat.app.spaces.create chat.app.spaces
Criar e adicionar participantes a um espaço		—	Com a autenticação do usuário: chat.spaces.create chat.spaces
Adicionar um usuário a um espaço			Com a Autenticação do usuário: chat.memberships chat.memberships.app chat.import Com a autenticação de apps e a aprovação do administrador (disponível na prévia para desenvolvedores): chat.app.memberships
Lista de atividades ou eventos de um espaço do Chat		—	Com a autenticação do usuário, você precisa usar um escopo para cada tipo de evento incluído na solicitação: Para eventos relacionados a mensagens: chat.messages chat.messages.readonly Para eventos sobre reações: chat.messages.reactions chat.messages.reactions.readonly chat.messages chat.messages.readonly Para eventos sobre assinaturas: chat.memberships chat.memberships.readonly Para eventos sobre o espaço: chat.spaces chat.spaces.readonly

Escopos do Google Drive

Confira abaixo os escopos mais usados para complementos do Google Workspace que estendem o Google Drive.

Escopo
Ler os 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 que um usuário selecionou no Google Drive. Os metadados são limitados ao ID, ao título, ao tipo MIME, ao URL do ícone e à permissão do complemento 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 Google Drive do Apps Script. No entanto, isso não permite o uso de ações semelhantes usando o serviço básico do Drive. A autorização de arquivo é concedida por arquivo e é revogada quando o usuário desautoriza o app. Consulte o exemplo de solicitação de acesso a arquivos para arquivos selecionados.

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 a eles. 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.

Observação: o token de acesso que ativa os escopos do Gmail não é o mesmo que o token de acesso retornado por ScriptApp.getOAuthToken(). É necessário usar o token fornecido no objeto do 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();
}

Outros escopos do Google Workspace

Seu complemento pode exigir escopos adicionais se usar outros serviços do Google Workspace ou 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.

A tabela a seguir mostra uma lista de escopos que os complementos do Google Workspace costumam usar:

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 ligações 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 usar 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 saiba a localidade e o fuso horário do usuário atual. Consulte Como acessar a localidade e o fuso horário do usuário para mais detalhes.
Criar acionadores	https://www.googleapis.com/auth/script.scriptapp Permite que o projeto crie acionadores.
Visualizar links de terceiros	https://www.googleapis.com/auth/workspace.linkpreview Obrigatório se as prévias do complemento tiverem links de um serviço de terceiros. Permite que o projeto veja um link em um aplicativo 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 que os usuários enviam para o 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 "@".