Ambiti di autorizzazione

Gli utenti devono autorizzare i progetti di script che accedono ai loro dati o agiscono per loro conto. Quando un utente esegue per la prima volta uno script che richiede l'autorizzazione, l'interfaccia utente mostra un messaggio per avviare il flusso di autorizzazione.

Durante questo flusso, l'interfaccia utente comunica all'utente cosa vuole fare lo script. Ad esempio, uno script potrebbe richiedere l'autorizzazione per leggere i messaggi email dell'utente o creare eventi nel suo calendario. Il progetto dello script definisce queste singole autorizzazioni come ambiti OAuth.

Per la maggior parte degli script, Apps Script rileva automaticamente gli ambiti necessari. Puoi visualizzare gli ambiti utilizzati da uno script in qualsiasi momento. Puoi anche impostare gli ambiti in modo esplicito nel manifest utilizzando stringhe URL. A volte è necessario impostare esplicitamente gli ambiti per determinate applicazioni, come i componenti aggiuntivi, poiché le applicazioni pubblicate devono sempre utilizzare gli ambiti più ristretti possibili.

Durante il flusso di autorizzazione, Apps Script presenta all'utente descrizioni leggibili degli ambiti richiesti. Ad esempio, se lo script necessita di accesso di sola lettura ai fogli di lavoro, il manifest potrebbe avere l'ambito https://www.googleapis.com/auth/spreadsheets.readonly. Durante il flusso di autorizzazione, uno script con questo ambito chiede all'utente di consentire all'applicazione di "Visualizzare i tuoi Fogli Google".

Alcuni ambiti includono altri. Ad esempio, se autorizzato, l'ambitohttps://www.googleapis.com/auth/spreadsheets consente l'accesso in lettura e scrittura ai fogli di lavoro.

Per alcune piattaforme in cui vengono eseguiti gli script, ad esempio l'esecuzione di uno script direttamente dall'IDE di Apps Script, agli utenti viene presentata la schermata di consenso di OAuth granulare. In questo modo, gli utenti possono selezionare le autorizzazioni specifiche da concedere anziché concedere tutte le autorizzazioni contemporaneamente. È importante progettare lo script in modo da gestire le autorizzazioni OAuth granulari.

Visualizza gli ambiti

Per visualizzare gli ambiti attualmente richiesti dal tuo progetto di script, segui questi passaggi:

  1. Apri il progetto di script.
  2. A sinistra, fai clic su Panoramica .
  3. Visualizza gli ambiti in Ambiti OAuth del progetto.

Impostare ambiti espliciti

Apps Script determina automaticamente gli ambiti di cui uno script ha bisogno esaminando il codice per individuare le chiamate di funzione che li richiedono. Per la maggior parte degli script, questo è sufficiente e ti fa risparmiare tempo, ma per i componenti aggiuntivi pubblicati, le app web, le app Google Chat e le chiamate all'API Google Chat devi esercitare un controllo più diretto sugli ambiti.

A volte Apps Script assegna automaticamente ai progetti ambiti molto permissivi. Ciò può significare che lo script chiede all'utente più di quanto necessario, il che è una cattiva prassi. Per gli script pubblicati, devi sostituire gli ambiti ampi con un insieme più limitato che soddisfi le esigenze dello script e non di più.

Puoi impostare esplicitamente gli ambiti utilizzati dal progetto di script modificando il file manifest. Il campo manifestoauthScopes è un array di tutti gli ambiti utilizzati dal progetto. Per impostare gli scopi del progetto:

  1. Apri il progetto di script.
  2. A sinistra, fai clic su Impostazioni progetto .
  3. Seleziona la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.
  4. A sinistra, fai clic su Editor .
  5. A sinistra, fai clic sul file appsscript.json.
  6. Individua il campo di primo livello denominato oauthScopes. Se non è presente, puoi aggiungerlo.
  7. Il campo oauthScopes specifica un array di stringhe. Per impostare gli ambiti utilizzati dal progetto, sostituisci i contenuti di questo array con gli ambiti che vuoi utilizzare. Ad esempio: 
          {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
  8. In alto, fai clic su Salva .

Gestire le autorizzazioni OAuth granulari

La schermata di consenso OAuth granulare consente agli utenti di specificare i singoli ambiti OAuth che vogliono autorizzare. Le autorizzazioni OAuth granulari offrono agli utenti un controllo più granulare sui dati dell'account che scelgono di condividere con ogni script. Ad esempio, immagina di sviluppare uno script che richieda l'autorizzazione per gli ambiti email e calendario. Gli utenti potrebbero voler utilizzare lo script solo per le sue funzionalità con Google Calendar, ma non con Gmail. Con le autorizzazioni OAuth granulari, gli utenti possono scegliere di concedere solo l'autorizzazione Calendar, ma non Gmail.

Le sezioni seguenti descrivono i modi principali per gestire le autorizzazioni OAuth granulari.

Richiedi automaticamente l'autorizzazione per gli ambiti necessari

Se un flusso di esecuzione richiede l'autorizzazione per gli ambiti per funzionare, puoi richiedere agli utenti di concedere queste autorizzazioni prima di poterlo utilizzare. Lo script può verificare se l'utente ha già concesso l'autorizzazione e, in caso contrario, chiedergliela automaticamente.

I seguenti metodi della classe ScriptApp ti consentono di convalidare l'autorizzazione per gli ambiti richiesti ed eseguire automaticamente il rendering della richiesta di autorizzazione per richiedere le autorizzazioni mancanti:

Esempio

L'esempio seguente mostra come chiamare i metodi requireScopes(authMode, oAuthScopes) e requireAllScopes(authMode). Lo script utilizza gli ambiti per Gmail, Fogli e Calendar. La funzione sendEmail() richiede solo gli ambiti per Gmail e Tabelle, mentre la funzione createEventSendEmail() richiede tutti gli ambiti utilizzati dallo 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!");
}

Creare un'esperienza personalizzata per gli ambiti mancanti

Puoi ottenere i dettagli delle autorizzazioni dell'utente che esegue lo script e progettare un'esperienza personalizzata in base al suo stato di autorizzazione. Ad esempio, potresti decidere di disattivare funzionalità specifiche dello script che richiedono autorizzazioni non concesse dall'utente o presentare una finestra di dialogo personalizzata che spieghi le autorizzazioni mancanti. I seguenti metodi recuperano un oggetto con le informazioni sulle autorizzazioni dell'utente, inclusi gli ambiti che l'utente ha autorizzato, e un URL che ti consente di richiedere gli ambiti mancanti:

Per ottenere i dettagli delle autorizzazioni dall'oggetto delle informazioni di autorizzazione, ad esempio un elenco degli ambiti che sono stati autorizzati e un URL per richiedere le autorizzazioni mancanti, utilizza i metodi della classe AuthorizationInfo.

Esempio

L'esempio seguente mostra come chiamare il metodo getAuthorizationInfo(authMode, oAuthScopes) per saltare funzionalità specifiche all'interno di un flusso di esecuzione in cui gli ambiti richiesti non sono stati concessi. In questo modo, il resto del flusso di esecuzione continua senza dover richiedere l'autorizzazione per gli ambiti mancanti.

// 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...
}

Verifica OAuth

Alcuni ambiti OAuth sono sensibili perché consentono l'accesso ai dati utente di Google. Se il progetto di script utilizza ambiti che consentono l'accesso ai dati utente, deve essere sottoposto alla verifica del client OAuth prima di poter essere pubblicato pubblicamente come app web o componente aggiuntivo. Per ulteriori informazioni, consulta le seguenti guide:

Ambiti con restrizioni

Oltre agli ambiti sensibili, alcuni sono classificati come con restrizioni e soggetti a regole aggiuntive che contribuiscono a proteggere i dati utente. Se intendi pubblicare un'app web o un componente aggiuntivo che utilizza uno o più ambiti con restrizioni, l'app deve essere conforme a tutte le limitazioni specificate prima di poter essere pubblicata.

Consulta l'elenco completo degli ambiti con restrizioni prima di tentare di pubblicare. Se la tua app li utilizza, devi rispettare i Requisiti aggiuntivi per gli ambiti API specifici prima della pubblicazione.