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 uno script che richiede l'autorizzazione per la prima volta, l'interfaccia utente mostra un prompt per avviare il flusso di autorizzazione.

Durante questo flusso, l'interfaccia utente indica agli utenti le autorizzazioni richieste dallo script. Ad esempio, uno script potrebbe richiedere l'autorizzazione per leggere i messaggi email o creare eventi di calendario. Il progetto di script definisce queste singole autorizzazioni come ambiti OAuth.

Per la maggior parte degli script, Apps Script rileva automaticamente gli ambiti richiesti. Puoi visualizzare gli ambiti utilizzati da uno script in qualsiasi momento. Puoi anche impostare gli ambiti in modo esplicito nel manifest utilizzando stringhe URL. Le applicazioni pubblicate, come i componenti aggiuntivi, devono utilizzare gli ambiti più ristretti possibili.

Durante il flusso di autorizzazione, Apps Script presenta descrizioni leggibili degli ambiti richiesti. Ad esempio, se lo script deve accedere in sola lettura ai fogli di lavoro, il manifest potrebbe includere l'ambito https://www.googleapis.com/auth/spreadsheets.readonly. La richiesta di autorizzazione chiede all'utente di "Visualizzare i tuoi Fogli Google".

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

Per alcune piattaforme, come l'IDE Apps Script, gli utenti visualizzano la schermata per il consenso OAuth granulare. Questa schermata consente agli utenti di selezionare autorizzazioni specifiche da concedere anziché concederle tutte contemporaneamente. Progetta lo script in modo da gestire le autorizzazioni OAuth granulari.

Visualizza gli ambiti

Per visualizzare gli ambiti richiesti dal tuo progetto di script:

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

Impostare ambiti espliciti

Apps Script determina automaticamente gli ambiti richiesti eseguendo la scansione del codice per le chiamate di funzione. Sebbene questo sia sufficiente per la maggior parte degli script, devi esercitare un controllo più diretto per i componenti aggiuntivi pubblicati, le app web, le app di chat e le chiamate all'API Chat.

A volte Apps Script assegna automaticamente ambiti permissivi. Ciò può significare che lo script chiede agli utenti un accesso superiore a quello necessario. Per gli script pubblicati, sostituisci gli ambiti generici con un insieme limitato che copra le esigenze dello script.

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

1. Apri il progetto di script.
2. A sinistra, fai clic su Impostazioni progetto settings.
3. Seleziona la casella di controllo Mostra il file manifest "appsscript.json" nell'editor.
4. A sinistra, fai clic su Editor code.
5. A sinistra, fai clic sul file appsscript.json.
6. Individua il campo di primo livello etichettato oauthScopes. Se non è presente, puoi aggiungerlo.
7. Sostituisci i contenuti dell'array oauthScopes con gli ambiti che vuoi che il progetto utilizzi. Ad esempio:

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

8. In alto, fai clic su Salva save.

Gestire le autorizzazioni OAuth granulari

La schermata per il consenso OAuth granulare è stata lanciata per la prima volta nell'IDE Apps Script per gli utenti che eseguono uno script direttamente. La schermata del consenso viene rilasciata progressivamente ad altre piattaforme, come macro, trigger e componenti aggiuntivi, nel tempo. Per ulteriori informazioni, consulta Consenso OAuth granulare nelle esecuzioni dell'IDE di Google Apps Script.

La schermata di consenso OAuth granulare consente agli utenti di specificare quali singoli ambiti OAuth autorizzare. In questo modo gli utenti hanno un controllo granulare sui dati dell'account che condividono con ogni script. Ad esempio, se uno script richiede ambiti email e calendario, gli utenti possono scegliere di concedere l'autorizzazione per Calendar ma non per Gmail.

Le sezioni seguenti descrivono come gestire le autorizzazioni OAuth granulari.

Richiedere automaticamente l'autorizzazione per gli ambiti necessari

Se un flusso di esecuzione richiede ambiti specifici, puoi richiedere agli utenti di concedere queste autorizzazioni. Lo script può verificare le autorizzazioni e richiederle automaticamente se mancano.

I seguenti metodi della classe ScriptApp convalidano le autorizzazioni e visualizzano la richiesta di autorizzazione:

• requireScopes(authMode, oAuthScopes): utilizza questo metodo per i flussi che si basano su ambiti specifici.
• requireAllScopes(authMode): utilizza questo metodo se un flusso di esecuzione si basa su tutti gli ambiti del progetto.

Esempio

L'esempio seguente mostra come chiamare requireScopes() e requireAllScopes(). Lo script utilizza gli ambiti per Gmail, Fogli e Calendar. La funzione sendEmail() richiede solo gli ambiti per Gmail e Fogli, 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 recuperare lo stato delle autorizzazioni degli utenti e progettare esperienze personalizzate. Ad esempio, potresti disattivare le funzionalità che richiedono autorizzazioni mancanti o visualizzare una finestra di dialogo che spiega il requisito. I seguenti metodi recuperano un oggetto con le informazioni sulle autorizzazioni dell'utente, inclusi gli ambiti che l'utente ha autorizzato e un URL per richiedere gli ambiti mancanti:

• getAuthorizationInfo(authMode, oAuthScopes): Controlla lo stato dell'autorizzazione per ambiti specifici.
• getAuthorizationInfo(authMode): Controlla lo stato delle autorizzazioni per tutti gli ambiti del progetto.

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

Esempio

L'esempio seguente mostra come utilizzare getAuthorizationInfo() per ignorare le funzionalità per cui gli utenti non hanno concesso gli ambiti richiesti. Ciò consente al resto del flusso di esecuzione di continuare senza richiedere l'autorizzazione degli 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...
}

Assicurati che le esecuzioni dei trigger dispongano delle autorizzazioni

Le funzioni associate ai trigger vengono eseguite automaticamente e gli utenti potrebbero non essere presenti per fornire le autorizzazioni. Ti consigliamo di utilizzare requireScopes(authMode, oAuthScopes) prima di installare un trigger. In questo modo viene richiesto all'utente di concedere le autorizzazioni mancanti e non viene consentita l'installazione del trigger senza queste autorizzazioni.

Esempio

// 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 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 poterlo pubblicare pubblicamente come app web o componente aggiuntivo. Per saperne di più, consulta le guide seguenti:

• Verifica del client OAuth per Apps Script
• App non verificate
• Domande frequenti sulla verifica OAuth
• Servizi API di Google: norme relative ai dati utente

Ambiti con restrizioni

Oltre agli ambiti sensibili, alcuni ambiti sono classificati come con restrizioni e sono soggetti a regole aggiuntive che contribuiscono a proteggere i dati utente. Se pubblichi un'app che utilizza ambiti con limitazioni, deve rispettare tutte le specifiche.

Prima di pubblicare, consulta l'elenco completo degli ambiti con restrizioni. Le app conformi devono rispettare i Requisiti aggiuntivi per gli ambiti API specifici.

Se possibile, evita di utilizzare ambiti con limitazioni per semplificare la procedura di revisione. Puoi utilizzare gli ambiti con limitazioni liberamente per le app non pubbliche.