Escopos de 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 interface apresenta uma solicitação para iniciar o fluxo de autorização.

Durante esse fluxo, a interface informa ao usuário o que o script quer permissão para fazer. Por exemplo, um script pode precisar de permissão para ler as mensagens de e-mail do usuário ou criar eventos na agenda dele. 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, é necessário definir escopos explicitamente para determinados aplicativos, como complementos, uma vez que os aplicativos publicados precisam usar sempre os escopos mais restritos possíveis.

Durante o fluxo de autorização, o Apps Script apresenta descrições legíveis dos escopos necessários para o usuário. Por exemplo, se o script precisa de acesso para ler as 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 atualmente, faça o seguinte:

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

Definir escopos explícitos

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

Às vezes, o Apps Script atribui 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, é preciso substituir escopos amplos por um conjunto mais limitado que atenda às necessidades do script e nada mais.

Para definir explicitamente os escopos usados pelo projeto de script, edite o arquivo de manifesto. O campo do 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 Project Settings .
  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 pelo projeto, substitua o conteúdo dessa matriz pelos escopos que você quer que ela use. 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 OAuth são confidenciais porque permitem acesso aos dados do usuário do Google. Se o projeto de script usar escopos que permitem acesso a dados do usuário, ele precisará passar pela verificação do cliente OAuth antes de publicá-lo publicamente como um app da Web ou complemento. Para mais informações, consulte estes guias:

Escopos restritos

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

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.