Escopos de autorização

Os usuários precisam autorizar projetos de script que acessam os dados deles ou agem em nome deles. Quando um usuário executa um script que exige 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 fazer. Por exemplo, um script pode querer permissão para ler as mensagens de e-mail do usuário ou criar eventos na agenda dele. O projeto do 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. Você pode acessar os escopos usados por um script a qualquer momento. Também é possível definir escopos de forma explícita no seu manifesto usando strings de URL. A definição de escopos explicitamente às vezes é necessária para determinados aplicativos, como complementos, já que os aplicativos publicados precisam sempre usar os escopos mais estreitos possíveis.

Durante o fluxo de autorização, o Apps Script apresenta descrições legíveis pelo usuário 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 pede ao usuário para permitir que o aplicativo "acesse 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 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.

Como definir escopos explícitos

O Apps Script determina automaticamente quais escopos um script precisa analisando 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, apps da Web, apps do Google Chat e chamadas para a API Google Chat, é necessário ter um controle mais direto dos escopos.

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

É possível definir explicitamente os escopos usados pelo projeto de script editando o arquivo manifesto. O campo de 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 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 com a etiqueta oauthScopes. Se ele não estiver presente, adicione-o.
  7. O campo oauthScopes especifica uma matriz de strings. Para definir os escopos que seu projeto usa, substitua o conteúdo desse array pelos escopos que você quer usar. 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 do cliente OAuth antes de ser publicado publicamente como um app da Web ou complemento. Para mais informações, consulte estes guias:

Escopos restritos

Além dos escopos sensíveis, alguns escopos são classificados como restritos e estão sujeitos a regras adicionais 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.

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