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 mostra 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 querer 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 ver os escopos usados por um script a qualquer momento. Também é possível definir escopos de forma explícita no manifesto usando strings de URL. Às vezes, é necessário definir escopos explicitamente para determinados aplicativos, como complementos, já que os aplicativos publicados sempre devem 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 esse escopo pede ao usuário para permitir que o aplicativo "Veja 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.

Em algumas plataformas em que os scripts são executados, como um script diretamente do ambiente de desenvolvimento integrado do Apps Script, os usuários veem a tela de permissão OAuth granular. Assim, os usuários podem selecionar permissões específicas para conceder, em vez de conceder todas de uma vez. É importante projetar seu script para processar permissões granulares do OAuth.

Ver escopos

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

Definir escopos explícitos

O Apps Script determina automaticamente quais escopos um script precisa ao verificar 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 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 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 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 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 dessa matriz pelos escopos que você quer que ele use. Exemplo: 
          {         ...         "oauthScopes": [           "https://www.googleapis.com/auth/spreadsheets.readonly",           "https://www.googleapis.com/auth/userinfo.email"         ],        ...       }
  8. Na parte superior, clique em Salvar .

Processar permissões granulares do OAuth

A tela de permissão OAuth granular permite que os usuários especifiquem quais escopos individuais eles querem autorizar. Com as permissões granulares do OAuth, os usuários têm um controle mais detalhado sobre quais dados da conta eles compartilham com cada script. Por exemplo, imagine que você desenvolva um script que solicite permissão para escopos de e-mail e agenda. Seus usuários podem querer usar o script apenas para as funcionalidades do Google Agenda, mas não do Gmail. Com as permissões granulares do OAuth, os usuários podem escolher conceder apenas permissão da Agenda, mas não do Gmail.

As seções a seguir descrevem as principais maneiras de processar permissões granulares do OAuth.

Exigir permissão automaticamente para os escopos necessários

Se um fluxo de execução precisar de permissão para escopos para funcionar, você pode exigir que os usuários concedam essas permissões antes de usar. O script pode verificar se o usuário já deu permissão e, se não, pedir automaticamente.

Os métodos a seguir da classe ScriptApp permitem validar a permissão para os escopos necessários e renderizar automaticamente a solicitação de autorização para pedir permissões ausentes:

Exemplo

O exemplo a seguir mostra como chamar os métodos requireScopes(authMode, oAuthScopes) e requireAllScopes(authMode). O script usa escopos para Gmail, Planilhas e Agenda. A função sendEmail() exige apenas os escopos do Gmail e Planilhas , enquanto a função createEventSendEmail() exige todos os escopos usados pelo script.

// This function requires the Gmail and Sheets scopes. function sendEmail() {   // Validates that the user has granted permission for the Gmail and Sheets scopes.   // If not, the execution ends and prompts the user for authorization.   ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [     'https://mail.google.com/',     'https://www.googleapis.com/auth/spreadsheets'   ]);    // Sends an email.   GmailApp.sendEmail("[email protected]", "Subject", "Body");   Logger.log("Email sent successfully!");    // Opens a spreadsheet and sheet to track the sent email.   const ss = SpreadsheetApp.openById("abc1234567");   const sheet = ss.getSheetByName("Email Tracker")    // Gets the last row of the sheet.   const lastRow = sheet.getLastRow();    // Adds "Sent" to column E of the last row of the spreadsheet.   sheet.getRange(lastRow, 5).setValue("Sent");   Logger.log("Sheet updated successfully!"); }  // This function requires all scopes used by the script (Gmail, // Calendar, and Sheets). function createEventSendEmail() {   // Validates that the user has granted permission for all scopes used by the   // script. If not, the execution ends and prompts the user for authorization.   ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);    // Creates an event.   CalendarApp.getDefaultCalendar().createEvent(     "Meeting",     new Date("November 28, 2024 10:00:00"),     new Date("November 28, 2024 11:00:00")   );   Logger.log("Calendar event created successfully!");    // Sends an email.   GmailApp.sendEmail("[email protected]", "Subject 2", "Body 2");   Logger.log("Email sent successfully!");    // Opens a spreadsheet and sheet to track the created meeting and sent email.   const ss = SpreadsheetApp.openById("abc1234567");   const sheet = ss.getSheetByName("Email and Meeting Tracker")   // Gets the last row   const lastRow = sheet.getLastRow();    // Adds "Sent" to column E of the last row   sheet.getRange(lastRow, 5).setValue("Sent");   // Adds "Meeting created" to column F of the last row   sheet.getRange(lastRow, 6).setValue("Meeting created");   Logger.log("Sheet updated successfully!"); }

Criar uma experiência personalizada para escopos ausentes

Você pode acessar os detalhes de permissão do usuário que está executando o script e criar uma experiência personalizada com base no status de permissão dele. Por exemplo, você pode desativar recursos específicos do script que exigem permissões que o usuário não concedeu ou apresentar uma caixa de diálogo personalizada explicando as permissões ausentes. Os métodos a seguir recebem um objeto com as informações de permissão do usuário, incluindo os escopos que ele autorizou e um URL para solicitar os escopos ausentes:

Para receber os detalhes da permissão do objeto de informações de autorização, como uma lista de quais escopos foram autorizados e um URL para solicitar permissões ausentes, use os métodos da classe AuthorizationInfo.

Exemplo

O exemplo a seguir mostra como chamar o método getAuthorizationInfo(authMode, oAuthScopes) para pular recursos específicos em um fluxo de execução em que os escopos necessários não foram concedidos. Isso permite que o restante do fluxo de execução continue sem precisar solicitar a autorização dos escopos ausentes.

// This function uses the Gmail scope and skips the email // capabilities if the scope for Gmail hasn't been granted. function myFunction() {   const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);   if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {     GmailApp.sendEmail("[email protected]", "Subject", "Body");     Logger.log("Email sent successfully!");   } else {     const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();     console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);   }   // Continue the rest of the execution flow... }

Verificar se as execuções de gatilho têm permissões

As funções associadas a acionadores podem ser executadas automaticamente em determinados eventos, e o usuário pode não estar presente para conceder mais permissões. Recomendamos que você use requireScopes(authMode, oAuthScopes) antes de instalar um gatilho. Isso solicita ao usuário as permissões ausentes e não permite a instalação do gatilho sem elas.

Exemplo

// This function requires scope Sheets. function trackFormSubmissions(e){   // Opens a spreadsheet to track the sent email.   const ss = SpreadsheetApp.openById("abc1234567");   const sheet = ss.getSheetByName("Submission Tracker")    // Gets the last row of the sheet.   const lastRow = sheet.getLastRow();    // Adds email address of user that submitted the form   // to column E of the last row of the spreadsheet.   sheet.getRange(lastRow, 5).setValue(e.name);   Logger.log("Sheet updated successfully!"); }   function installTrigger(){   // Validates that the user has granted permissions for trigger   // installation and execution. If not, trigger doesn't get   // installed and prompts the user for authorization.   ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [     'https://www.googleapis.com/auth/script.scriptapp',     'https://www.googleapis.com/auth/spreadsheets',     'https://www.googleapis.com/auth/forms.currentonly'   ]);   ScriptApp.newTrigger('trackFormSubmission')     .forForm(FormApp.getActiveForm())     .onFormSubmit()     .create(); }

Verificação do OAuth

Alguns escopos do OAuth são sensíveis porque permitem acesso aos dados de usuário do Google. Se o projeto de script usar escopos que permitem o acesso a 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 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 web app ou 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 usa alguma delas, é preciso obedecer aos Outros requisitos para escopos específicos de API antes da publicação.