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 aos usuários quais permissões o script solicita. Por exemplo, um script pode pedir permissão para ler mensagens de e-mail ou criar eventos da 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. Você pode conferir os escopos que um script usa a qualquer momento. Também é possível definir escopos de forma explícita no manifesto usando strings de URL. Os aplicativos publicados, como complementos, precisam usar os escopos mais restritos possíveis.

Durante o fluxo de autorização, o Apps Script apresenta descrições legíveis dos escopos necessários. Por exemplo, se o script precisar de acesso somente leitura às planilhas, o manifesto poderá incluir o escopo https://www.googleapis.com/auth/spreadsheets.readonly. A solicitação de autorização pede que o usuário "Veja suas planilhas Google".

Alguns escopos incluem outros. Por exemplo, o acesso autorizado a https://www.googleapis.com/auth/spreadsheets permite acesso de leitura e gravação a planilhas.

Em algumas plataformas, como o ambiente de desenvolvimento integrado do Apps Script, os usuários veem a tela de permissão OAuth granular. Nela, os usuários podem selecionar permissões específicas em vez de conceder todas de uma vez. Projete seu script para processar permissões granulares do OAuth.

Ver escopos

Para ver os escopos necessários para seu projeto de script:

Abra o projeto de script.
À esquerda, clique em Visão geral .
Confira os escopos em Escopos OAuth do projeto.

Definir escopos explícitos

O Apps Script determina automaticamente os escopos necessários ao analisar o código em busca de chamadas de função. Embora isso seja suficiente para a maioria dos scripts, você precisa exercer um controle mais direto para complementos, apps da Web, apps do Chat e chamadas para a API Chat publicados.

Às vezes, o Apps Script atribui escopos permissivos automaticamente. Isso pode significar que o script pede aos usuários mais acesso do que o necessário. Para scripts publicados, substitua os escopos amplos por um conjunto limitado que atenda às necessidades do script.

É possível definir explicitamente os escopos usados pelo projeto de script editando o arquivo de manifesto. O campo oauthScopes do manifesto é uma matriz de escopos usados pelo projeto. Para definir os escopos do projeto:

Abra o projeto de script.
À esquerda, clique em Configurações do projeto .
Selecione a caixa de seleção Mostrar arquivo de manifesto "appsscript.json" no editor.
À esquerda, clique em Editor .
À esquerda, clique no arquivo appsscript.json.
Localize o campo de nível superior chamado oauthScopes. Se ele não estiver presente, adicione-o.

Substitua o conteúdo da matriz oauthScopes pelos escopos que você quer que o projeto use. Exemplo:

      {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }

Na parte de cima, clique em Salvar .

Processar permissões granulares do OAuth

A tela de permissão OAuth granular foi lançada primeiro para o ambiente de desenvolvimento integrado do Apps Script para usuários que executam um script diretamente. A tela de permissão é lançada progressivamente para outras plataformas, como macros, gatilhos 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 permissão OAuth granular permite que os usuários especifiquem quais escopos individuais eles querem autorizar. Isso dá aos usuários controle refinado sobre quais dados da conta eles compartilham com cada script. Por exemplo, se um script solicitar escopos de e-mail e agenda, os usuários poderão conceder permissão à Agenda mas não ao Gmail.

As seções a seguir descrevem como processar permissões granulares do OAuth.

Exigir permissão automaticamente para os escopos necessários

Se um fluxo de execução exigir escopos específicos, você poderá exigir que os usuários concedam essas permissões. Seu script pode verificar as permissões e solicitá-las automaticamente se estiverem faltando.

Os métodos a seguir da classe ScriptApp validam permissões e renderizam a solicitação de autorização:

requireScopes(authMode, oAuthScopes): use esse método para fluxos que dependem de escopos específicos.
requireAllScopes(authMode): use esse método se um fluxo de execução depender de todos os escopos do projeto.

Exemplo

O exemplo a seguir mostra como chamar requireScopes() e requireAllScopes(). O script usa escopos para Gmail, Planilhas e Agenda. A função sendEmail() requer apenas os escopos do Gmail e das Planilhas enquanto a função createEventSendEmail() requer 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("dana@example.com", "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("dana@example.com", "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 recuperar o status de permissão dos usuários e criar experiências personalizadas. Por exemplo, você pode desativar recursos que exigem permissões ausentes ou mostrar uma caixa de diálogo explicando a exigência. Os métodos a seguir recuperam um objeto com as informações de permissão do usuário, incluindo os escopos autorizados e um URL para solicitar os escopos ausentes:

getAuthorizationInfo(authMode, oAuthScopes): verifica o status de permissão para escopos específicos.
getAuthorizationInfo(authMode): verifica o status de permissão para todos os escopos do projeto.

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

Exemplo

O exemplo a seguir mostra como usar getAuthorizationInfo() para pular recursos em que os usuários não concederam os escopos necessários. Isso permite que o restante do fluxo de execução continue sem solicitar 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("dana@example.com", "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 são executadas automaticamente, e os usuários podem não estar presentes para conceder 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 do 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ê publicar um app que usa escopos restritos, ele precisará obedecer a todas as especificações.

Consulte a lista completa de escopos restritos antes de publicar. Os apps em conformidade precisam seguir os Outros requisitos para escopos específicos de API.

Evite usar escopos restritos, se possível, para simplificar o processo de revisão. É possível usar escopos restritos livremente para apps não públicos.

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

Ver escopos

Definir escopos explícitos

Processar permissões granulares do OAuth

Exigir permissão automaticamente para os escopos necessários

Exemplo

Criar uma experiência personalizada para escopos ausentes

Exemplo

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

Exemplo

Verificação do OAuth

Escopos restritos

Escopos de autorização