Escopos da autorização

Os usuários precisam autorizar projetos de script que acessam os dados ou atuam em nome deles. Quando um usuário executa um script que requer autorização pela primeira vez, a IU apresenta uma solicitação para iniciar o fluxo de autorização.

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

Para a maioria dos scripts, o Apps Script detecta automaticamente quais escopos são necessários para você. É possível conferir os escopos que um script usa a qualquer momento. Também é possível definir escopos de forma explícita no seu manifesto usando strings de URL. Às vezes, a definição de escopos explicitamente é necessária para determinados aplicativos, como complementos, já que os aplicativos publicados precisam sempre usar os escopos mais restritos possíveis.

Durante o fluxo de autorização, o Apps Script apresenta ao usuário descrições legíveis dos escopos necessários. Por exemplo, se o script precisa de acesso somente leitura às planilhas, o manifesto pode ter o escopo https://www.googleapis.com/auth/spreadsheets.readonly. Durante o fluxo de autorização, um script com esse escopo solicita que o usuário permita que o aplicativo "visualize suas Planilhas Google".

Alguns escopos incluem outros. Por exemplo, quando autorizado, o escopo https://www.googleapis.com/auth/spreadsheets permite acesso de leitura e gravação a planilhas.

Como visualizar escopos

Para ver 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. Veja os escopos em Escopos OAuth do projeto.

Definir escopos explícitos

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

Às vezes, o Apps Script atribui automaticamente escopos muito permissivos aos projetos. Isso pode significar que o script solicita ao usuário mais do que o necessário, o que é uma prática não recomendada. Para scripts publicados, substitua escopos amplos por um conjunto mais limitado que atenda às necessidades do script e nada mais.

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

  1. Abra o projeto de script.
  2. À esquerda, clique em Configurações do projeto .
  3. Selecione a caixa de seleção Mostrar arquivo de manifesto "appsscript.json" no editor.
  4. À esquerda, clique em Editor .
  5. À esquerda, clique no arquivo appsscript.json.
  6. Localize o campo de nível superior chamado oauthScopes. Se não estiver presente, você pode adicioná-lo.
  7. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos usados no projeto, substitua o conteúdo dessa matriz pelos escopos que você quer usar. Por exemplo: 
          {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
  8. Na parte superior, clique em Salvar .

Verificação do OAuth

Alguns escopos do OAuth são confidenciais porque permitem o acesso aos dados do usuário do Google. Se o projeto de script usar escopos que permitem o acesso aos dados do usuário, ele precisará passar pela verificação do cliente OAuth antes de publicá-lo como um app da Web ou complemento. Para mais informações, consulte estes guias:

Escopos restritos

Além dos escopos confidenciais, alguns escopos são classificados como restritos e estão sujeitos a outras regras para proteger os dados do usuário. Se você pretende publicar um app da Web ou complemento que usa um ou mais escopos restritos, o app precisa obedecer a todas as restrições especificadas antes da publicação.

Analise a lista completa de escopos restritos antes de tentar publicar. Se o app usar qualquer um deles, será necessário obedecer aos outros requisitos para escopos específicos da API antes da publicação.