Escopos de autorização para complementos do Editor

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

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, seu complemento pode usar o escopo "Ler documento atual", que é gravado no manifesto como https://www.googleapis.com/auth/documents.currentonly. Durante o fluxo de autorização, um complemento com esse escopo pede ao usuário para permitir que ele veja e gerencie documentos em que o aplicativo foi instalado.

Os escopos que o Apps Script usa para os vários serviços dele se sobrepõem aos escopos usados pela API relacionada. Por exemplo, o serviço Calendar do Apps Script usa muitos dos mesmos escopos da API Calendar. Você pode consultar os escopos necessários para métodos específicos do serviço do Apps Script na documentação de referência do Apps Script.

Ver 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 .
  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.

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, é recomendável exercer um controle mais direto dos escopos.

Por exemplo, o Apps Script pode dar 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 cubra as necessidades dos complementos 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 usados 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 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 Editor que estende o Planilhas você pode ter o seguinte:

     {
   ...
   "oauthScopes": [
     "https://www.googleapis.com/auth/script.container.ui",
     "https://www.googleapis.com/auth/spreadsheets"
   ],
   ...
 }

  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:

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.

Confira a lista completa de escopos restritos antes de tentar publicar. Se o complemento usar alguma delas, você precisará obedecer aos Outros requisitos para escopos específicos de API 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.

Escopos do complemento do Editor

Ao criar um complemento do Editor, os escopos necessários são determinados pelo serviço e pelos métodos do Google Apps Script que o código do complemento usa. Por exemplo, um complemento do Google Planilhas pode precisar do escopo https://www.googleapis.com/auth/spreadsheets.readonly para ler informações de diferentes planilhas.

O Apps Script determina automaticamente os escopos necessários para os serviços que você usa ao adicionar código ao projeto de script. Para complementos do Editor, muitas vezes basta confiar nessa coleta automática de escopos em vez de determinar os escopos por conta própria e defini-los explicitamente.

Se você não estiver definindo seus escopos explicitamente e seu complemento do Editor apenas ler ou gravar no arquivo do editor aberto, adicione o seguinte comentário a um dos arquivos do projeto de script:

/**
 * @OnlyCurrentDoc
 */

Esse comentário informa ao Apps Script para restringir os escopos de arquivo do editor que ele define como currentonly. Por exemplo, se você adicionar esse comentário a um arquivo de projeto de script de complemento das Planilhas, estará especificando que o complemento só precisa de permissão para operar na planilha aberta, e não em outras planilhas que o usuário possa ter no Google Drive. Por outro lado, não use esse comentário se o complemento do Planilhas precisar ler ou gravar dados em uma planilha que o usuário não abriu.