Escopos da autorização

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Os usuários precisam autorizar projetos de script que acessam os dados deles ou agir 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 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 os escopos necessários. É possível ver os escopos que um script usa a qualquer momento. Também é possível definir escopos explicitamente no manifesto usando strings de URL. Às vezes, é necessário definir explicitamente os escopos 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 precisar de acesso somente leitura às suas planilhas, o manifesto poderá ter o escopo https://www.googleapis.com/auth/spreadsheets.readonly. Durante o fluxo de autorização, um script com este escopo pede ao usuário que permita que esse aplicativo use "quot;Ver suas planilhas do Google"".

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

Como ver escopos

É possível ver os escopos exigidos pelo projeto de script no momento:

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

Como definir escopos explícitos

O Apps Script determina automaticamente os escopos de que um script precisa, verificando o código dele para 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 exercer um controle mais direto dos escopos.

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

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

  1. Abra o projeto de script.
  2. À esquerda, clique em Project Settings .
  3. Marque a caixa de seleção Mostrar "appsscript.json" arquivo de manifesto 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 ele não estiver presente, adicione-o.
  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 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 sensíveis 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 de 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, certos escopos são classificados como restritos e sujeitos a outras regras que ajudam a proteger os dados do usuário. Se você pretende publicar um app da Web ou complemento que use um ou mais escopos restritos, o app precisa estar em conformidade com todas as restrições especificadas antes da publicação.

Consulte a lista completa de escopos restritos antes de tentar publicar. Caso seu app use algum deles, será necessário obedecer aos requisitos adicionais para escopos específicos da API antes da publicação.