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 para o 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.

Para algumas plataformas em que os scripts são executados, como a execução de um script diretamente do ambiente de desenvolvimento integrado do Apps Script, os usuários recebem a tela de consentimento granular do OAuth. Isso permite que os usuários selecionem permissões específicas para conceder em vez de conceder todas de uma só vez. É importante projetar o script para processar permissões granulares do OAuth.

Acessar 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.

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.

Aviso: sempre use o conjunto de escopo menos permissivo possível. Para proteger as informações do usuário, os complementos e outros aplicativos publicados não podem nunca solicitar mais permissões de escopo do que o necessário.

É 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 .

Processar permissões granulares do OAuth

Observação: a tela de permissão OAuth detalhada foi lançada pela primeira vez no ambiente de desenvolvimento integrado do Apps Script para usuários que executam um script diretamente no Apps Script. A tela de consentimento será lançada progressivamente nas plataformas restantes, como macros, execuções de acionadores e complementos ao longo do tempo. Para mais informações, consulte Permissão OAuth detalhada em execuções no ambiente de desenvolvimento integrado do Google Apps Script.

A tela de consentimento OAuth detalhada permite que os usuários especifiquem quais escopos individuais do OAuth eles querem autorizar. As permissões granulares do OAuth dão aos usuários um controle mais detalhado sobre quais dados da conta eles compartilham com cada script. Por exemplo, imagine que você desenvolve um script que solicita permissão para os escopos de e-mail e de agenda. Talvez os usuários queiram usar seu script apenas para os recursos do Google Agenda, e não do Gmail. Com as permissões granulares do OAuth, os usuários podem escolher conceder apenas a 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ê poderá exigir que os usuários concedam essas permissões antes de usá-lo. Seu script pode verificar se o usuário já concedeu a 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 solicitar as permissões ausentes:

• requireScopes(authMode, oAuthScopes): use esse método para fluxos de execução que dependem de um ou mais escopos, mas não de todos os escopos usados pelo script.
• requireAllScopes(authMode): use esse método se um fluxo de execução depender de todos os escopos usados pelo script.

Exemplo

O exemplo a seguir mostra como chamar os métodos requireScopes(authMode, oAuthScopes) e requireAllScopes(authMode). O script usa escopos para o Gmail, as Planilhas e o Agenda. A função sendEmail() exige apenas os escopos do Gmail e das 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("[e-mail]", "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("[e-mail]", "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 receber os detalhes de permissão do usuário que executa o script e criar uma experiência personalizada com base no status de permissão. Por exemplo, você pode decidir 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 extraem um objeto com as informações de permissão do usuário, incluindo os escopos que o usuário autorizou, e um URL para solicitar os escopos ausentes:

• getAuthorizationInfo(authMode, oAuthScopes): use esse método para verificar o status de permissão de escopos específicos.
• getAuthorizationInfo(authMode): use esse método para verificar o status de permissão de todos os escopos usados pelo script.

Para conferir os detalhes da permissão do objeto de informações de autorização, como uma lista dos escopos que foram autorizados e um URL para solicitar as 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("[e-mail]", "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...
}

Verifique se as execuções de acionadores 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 acionador. Isso solicita ao usuário as permissões ausentes e não permite a instalação do acionador 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 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:

• Verificação de cliente OAuth para o Apps Script
• Apps não verificados
• Perguntas frequentes sobre a verificação OAuth
• Serviço de APIs do Google: política de dados do usuário

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.

Consulte 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.

Observação: evite usar escopos restritos no app, se possível. É mais fácil passar na revisão para publicação pública se você não os usar. É possível usar escopos restritos livremente para apps e scripts não públicos.