Class ScriptApp

ScriptApp

Accedere e gestire la pubblicazione e gli attivatori degli script. Questa classe consente agli utenti di creare attivatori di script e controllare la pubblicazione dello script come servizio.

Proprietà

ProprietàTipoDescrizione
AuthModeAuthModeUn'enumerazione che identifica le categorie di servizi autorizzati che Apps Script è in grado di eseguire tramite una funzione attivata.
AuthorizationStatusAuthorizationStatusUn'enumerazione che indica lo stato di autorizzazione di uno script.
EventTypeEventTypeUn'enumerazione che indica il tipo di evento attivato.
InstallationSourceInstallationSourceUn'enumerazione che indica come lo script è stato installato per l'utente come componente aggiuntivo.
TriggerSourceTriggerSourceUn'enumerazione che indica l'origine dell'evento che causa l'attivazione dell'attivatore.
WeekDayWeekdayUn'enumerazione che rappresenta i giorni della settimana.

Metodi

MetodoTipo restituitoBreve descrizione
deleteTrigger(trigger)voidRimuove il trigger specificato in modo che non venga più eseguito.
getAuthorizationInfo(authMode)AuthorizationInfoRestituisce un oggetto utilizzato per determinare se l'utente deve autorizzare questo script per utilizzare uno o più servizi e per fornire l'URL di una finestra di dialogo di autorizzazione.
getIdentityToken()StringRestituisce un token di identità OpenID Connect per l'utente effettivo, se è stato concesso l'ambito openid.
getInstallationSource()InstallationSourceRestituisce un valore enum che indica come è stato installato lo script come componente aggiuntivo per l'utente corrente, ad esempio se l'utente lo ha installato personalmente tramite il Chrome Web Store o se è stato installato da un amministratore di dominio per tutti gli utenti.
getOAuthToken()StringRecupera il token di accesso OAuth 2.0 per l'utente effettivo.
getProjectTriggers()Trigger[]Recupera tutti i trigger installabili associati al progetto e all'utente corrente.
getScriptId()StringRestituisce l'ID univoco del progetto di script.
getService()ServiceRestituisce un oggetto utilizzato per controllare la pubblicazione dello script come applicazione web.
getUserTriggers(document)Trigger[]Restituisce tutti i trigger installabili di proprietà di questo utente nel documento specificato, solo per questo script o componente aggiuntivo.
getUserTriggers(form)Trigger[]Recupera tutti i trigger installabili di proprietà di questo utente nel formato specificato, solo per questo script o componente aggiuntivo.
getUserTriggers(spreadsheet)Trigger[]Recupera tutti i trigger installabili di proprietà di questo utente nel foglio di lavoro specificato, solo per questo script o componente aggiuntivo.
invalidateAuth()voidAnnulla la validità dell'autorizzazione dell'utente effettivo per eseguire lo script corrente.
newStateToken()StateTokenBuilderCrea un generatore per un token di stato che può essere utilizzato in un'API di callback (ad esempio un flusso OAuth).
newTrigger(functionName)TriggerBuilderAvvia il processo di creazione di un attivatore installabile che, se attivato, chiama una determinata funzione.

Documentazione dettagliata

deleteTrigger(trigger)

Rimuove il trigger specificato in modo che non venga più eseguito. 

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Parametri

NomeTipoDescrizione
triggerTriggerL'attivatore da eliminare.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

Restituisce un oggetto utilizzato per determinare se l'utente deve autorizzare questo script per utilizzare uno o più servizi e per fornire l'URL di una finestra di dialogo di autorizzazione. Se lo script è pubblicato come componente aggiuntivo che utilizza attivabili installabili, queste informazioni possono essere utilizzate per controllare l'accesso alle sezioni di codice per le quali l'utente non dispone dell'autorizzazione necessaria. In alternativa, il componente aggiuntivo può chiedere all'utente di aprire l'URL della finestra di dialogo dell'autorizzazione per risolvere il problema. 

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

Parametri

NomeTipoDescrizione
authModeAuthModela modalità di autorizzazione per la quale vengono richieste le informazioni sull'autorizzazione; in quasi tutti i casi, il valore di authMode deve essere ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), poiché nessun'altra modalità di autorizzazione richiede che gli utenti concedano l'autorizzazione

Ritorni

AuthorizationInfo: un oggetto che può fornire informazioni sullo stato di autorizzazione dell'utente.

getIdentityToken()

Restituisce un token di identità OpenID Connect per l'utente effettivo, se è stato concesso l'ambito openid. Questo ambito non è incluso per impostazione predefinita e per richiederlo devi aggiungerlo come ambito esplicito nel file manifest. Includi gli ambiti https://www.googleapis.com/auth/userinfo.email o https://www.googleapis.com/auth/userinfo.profile per restituire ulteriori informazioni sull'utente nel token.

Il token ID restituito è un JSON Web Token (JWT) codificato e deve essere decodificato per estrarre informazioni. Gli esempi seguenti mostrano come decodificare il token ed estrarre l'ID del profilo Google dell'utente effettivo. 

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Consulta la documentazione su OpenID Connect per l'elenco completo dei campi (claim) restituiti.

Ritorni

String: il token di identità, se disponibile. In caso contrario, null.

getInstallationSource()

Restituisce un valore enum che indica come è stato installato lo script come componente aggiuntivo per l'utente corrente, ad esempio se l'utente lo ha installato personalmente tramite il Chrome Web Store o se è stato installato da un amministratore di dominio per tutti gli utenti.

Ritorni

InstallationSource: origine dell'installazione.

getOAuthToken()

Recupera il token di accesso OAuth 2.0 per l'utente effettivo. Se gli ambiti OAuth dello script sono sufficienti per autorizzare un'altra API di Google che normalmente richiede un proprio flusso OAuth (ad esempio Selettore Google), gli script possono ignorare la seconda richiesta di autorizzazione passando questo token. Il token scade dopo un determinato periodo di tempo (almeno pochi minuti); gli script dovrebbero gestire gli errori di autorizzazione e chiamare questo metodo per ottenere un nuovo token quando necessario.

Il token restituito da questo metodo include solo gli ambiti attualmente necessari per lo script. Gli ambiti precedentemente autorizzati, ma non più utilizzati dallo script, non sono inclusi nel token restituito. Se sono necessari altri ambiti OAuth oltre a quelli richiesti dallo script stesso, puoi specificarli nel file manifest dello script.

Ritorni

String: una rappresentazione stringa del token OAuth 2.0.

getProjectTriggers()

Recupera tutti i trigger installabili associati al progetto e all'utente corrente. 

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Ritorni

Trigger[]: un array dei trigger dell'utente corrente associati a questo progetto.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

Restituisce l'ID univoco del progetto di script. Questo è il metodo preferito per ottenere l'identificatore univoco per il progetto di script anziché getProjectKey(). Questo ID può essere utilizzato in tutte le posizioni in cui era precedentemente fornita la chiave del progetto.

Ritorni

String: ID del progetto di script.

getService()

Restituisce un oggetto utilizzato per controllare la pubblicazione dello script come applicazione web. 

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

Ritorni

Service: oggetto utilizzato per osservare e controllare la pubblicazione dello script come app web.

getUserTriggers(document)

Restituisce tutti i trigger installabili di proprietà di questo utente nel documento specificato, solo per questo script o componente aggiuntivo. Questo metodo non può essere utilizzato per visualizzare gli attivatori associati ad altri script. 

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Parametri

NomeTipoDescrizione
documentDocumentUn file di Documenti Google che può contenere attivatori installabili.

Ritorni

Trigger[]: array di attivatori di proprietà di questo utente nel documento specificato.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

Recupera tutti i trigger installabili di proprietà di questo utente nel formato specificato, solo per questo script o componente aggiuntivo. Questo metodo non può essere utilizzato per visualizzare gli attivatori associati ad altri script. 

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Parametri

NomeTipoDescrizione
formFormUn file di Moduli Google che può contenere attivatori installabili.

Ritorni

Trigger[]: array di attivatori di proprietà di questo utente nel formato specificato.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

Recupera tutti i trigger installabili di proprietà di questo utente nel foglio di lavoro specificato, solo per questo script o componente aggiuntivo. Questo metodo non può essere utilizzato per visualizzare gli attivatori associati ad altri script. 

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Parametri

NomeTipoDescrizione
spreadsheetSpreadsheetUn file di Fogli Google che può contenere attivatori installabili.

Ritorni

Trigger[]: array di attivatori di proprietà di questo utente nel foglio di lavoro specificato.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

Annulla la validità dell'autorizzazione dell'utente effettivo per eseguire lo script corrente. Utilizzato per invalidare eventuali autorizzazioni per lo script corrente. Ciò è particolarmente utile per le funzioni contrassegnate come autorizzazione one-shot. Poiché le funzioni di autorizzazione one-shot possono essere chiamate solo la prima esecuzione dopo che lo script ha acquisito l'autorizzazione, se vuoi eseguire un'azione in un secondo momento, devi revocare qualsiasi autorizzazione dello script, in modo che l'utente possa visualizzare di nuovo la finestra di dialogo di autorizzazione. 

ScriptApp.invalidateAuth();

Tiri

Error: quando l'annullamento della convalida non va a buon fine

newStateToken()

Crea un generatore per un token di stato che può essere utilizzato in un'API di callback (ad esempio un flusso OAuth). 

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Nella maggior parte dei flussi OAuth2, il token state viene trasmesso direttamente all'endpoint di autorizzazione (non all'interno dell'URL di callback) e l'endpoint di autorizzazione lo passa poi come parte dell'URL di callback.

Ad esempio:

  • Lo script reindirizza l'utente all'URL di autorizzazione OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • L'utente fa clic su Autorizza e la pagina di autorizzazione OAuth2 reindirizza l'utente a https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • Il reindirizzamento precedente (torna a http://script.google.com/...) causa la richiesta del browser a /usercallback, che richiama il metodo specificato da StateTokenBuilder.withMethod(method).

Ritorni

StateTokenBuilder: un oggetto utilizzato per continuare il processo di creazione del token di stato.

newTrigger(functionName)

Avvia il processo di creazione di un attivatore installabile che, se attivato, chiama una determinata funzione. 

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Parametri

NomeTipoDescrizione
functionNameStringLa funzione da chiamare quando viene attivato l'attivatore. Puoi utilizzare le funzioni delle librerie incluse, come Library.libFunction1.

Ritorni

TriggerBuilder: oggetto utilizzato per continuare il processo di creazione dei trigger.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

  • https://www.googleapis.com/auth/script.scriptapp

Metodi deprecati