Ambiti di autorizzazione

Gli utenti devono autorizzare i progetti di script che accedono ai loro dati o agiscono per loro conto. Per una panoramica generale di questo processo, consulta Autorizzazione per i servizi Google. 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 indica agli utenti le autorizzazioni richieste dallo script. Ad esempio, uno script potrebbe richiedere l'autorizzazione a 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 ha bisogno dell'accesso in sola lettura ai fogli di lavoro, il manifest potrebbe includere l'ambito https://www.googleapis.com/auth/spreadsheets.readonly. Il messaggio di autorizzazione chiede all'utente di "Visualizzare i fogli di lavoro Google".

Alcuni ambiti ne includono altri. 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 di Apps Script, gli utenti vedono 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 che gestisca le autorizzazioni OAuth granulari.

Visualizza gli ambiti

Per visualizzare gli ambiti richiesti dal progetto di script:

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

Imposta ambiti espliciti

Apps Script determina automaticamente gli ambiti richiesti analizzando il 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 Chat e le chiamate all'API Chat.

A volte Apps Script assegna automaticamente ambiti permissivi. Ciò significa che lo script chiede agli utenti un accesso maggiore di quello di cui ha bisogno. Per gli script pubblicati, sostituisci gli ambiti ampi con un insieme limitato che copra le esigenze dello script.

Avviso: utilizza sempre l'insieme di ambiti meno permissivo possibile. Per proteggere le informazioni degli utenti, i componenti aggiuntivi e altre applicazioni pubblicate non devono richiedere più autorizzazioni di ambito di quelle di cui hanno bisogno.

Puoi impostare in modo esplicito gli ambiti utilizzati dal progetto di script modificando il relativo file manifest. Il campo manifest oauthScopes è 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 .
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 con l'etichetta 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. Nella parte superiore della pagina, fai clic su Salva .

Gestisci le autorizzazioni OAuth granulari

La schermata per il consenso OAuth granulare è stata lanciata per la prima volta nell'IDE di Apps Script per gli utenti che eseguono uno script direttamente. La schermata per il 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 per il consenso OAuth granulare consente agli utenti di specificare gli ambiti OAuth individuali da autorizzare. In questo modo, gli utenti hanno un controllo preciso sui dati dell'account che condividono con ogni script. Ad esempio, se uno script richiede gli ambiti email e calendario, gli utenti possono scegliere di concedere l'autorizzazione a Calendar, ma non a Gmail.

Le sezioni seguenti descrivono come gestire le autorizzazioni OAuth granulari.

Richiedi 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 ScriptApp classe convalidano le autorizzazioni e visualizzano il messaggio 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("[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!");
}

Crea 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 autorizzati dall'utente e un URL per richiedere gli ambiti mancanti:

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

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

Esempio

L'esempio seguente mostra come utilizzare getAuthorizationInfo() per saltare le funzionalità in cui gli utenti non hanno concesso gli ambiti richiesti. In questo modo, il resto del flusso di esecuzione può 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("[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...
}

Assicurati che le esecuzioni dei trigger abbiano le 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, l'utente viene invitato a fornire le autorizzazioni mancanti e non è consentita l'installazione del trigger senza di esse.

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, il progetto deve essere sottoposto alla verifica del client OAuth prima di poterlo pubblicare pubblicamente come app web o componente aggiuntivo. Per ulteriori informazioni, consulta le seguenti guide:

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

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 restrizioni, deve rispettare tutte le specifiche.

Esamina l'elenco completo degli ambiti con restrizioni prima della pubblicazione. Le app conformi devono rispettare i Requisiti aggiuntivi per gli ambiti API specifici.

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