Escopos da autorização

Os usuários precisam autorizar projetos de script que acessem os dados deles ou agem em nome deles. Quando um usuário executa um script que requer autorização pela primeira vez, a interface apresenta um prompt 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 querer permissão para ler 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 visualizar 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. Às vezes, é necessário definir escopos explicitamente para determinados aplicativos, como complementos, já que os aplicativos publicados devem sempre usar os escopos mais estreitos 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 precisar de acesso somente leitura às planilhas, o manifesto poderá 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 esse 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 exigidos pelo projeto de script 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 do OAuth do projeto.

Definir escopos explícitos

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

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

Para definir explicitamente os escopos usados pelo projeto de script, edite o arquivo manifest. 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 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 rotulado como oauthScopes. Se não estiver presente, você pode adicioná-la.
  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 do OAuth são sensíveis, porque permitem o acesso a dados do usuário do Google. Se o projeto de script usa escopos que permitem acesso a dados do usuário, ele precisa passar pela verificação do cliente OAuth antes de ser publicado como um app da Web ou complemento. Para mais informações, consulte estes guias:

Escopos restritos

Além dos escopos confidenciais, alguns 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 use 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 algum deles, será preciso obedecer aos Requisitos adicionais para escopos específicos da API antes da publicação.