Class ScriptApp

App Script

Accedere e modificare la pubblicazione degli script e i relativi trigger. Questa classe consente agli utenti di creare trigger di script e controllare la pubblicazione dello script come servizio.

Proprietà

ProprietàTipoDescrizione
AuthModeAuthModeUn'enumerazione che identifica le categorie di servizi autorizzati da Apps Script che può 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 all'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 l'attivatore specificato in modo che non venga più eseguito.
getAuthorizationInfo(authMode)AuthorizationInfoVisualizza un oggetto utilizzato per determinare se l'utente deve autorizzare questo script a utilizzare uno o più servizi e per fornire l'URL per una finestra di dialogo di autorizzazione.
getIdentityToken()StringRecupera un token di identità OpenID Connect per l'utente efficace se l'ambito openid è stato concesso.
getInstallationSource()InstallationSourceRestituisce un valore di enumerazione che indica come lo script è stato installato come componente aggiuntivo per l'utente corrente (ad esempio, se l'utente lo ha installato personalmente tramite il Chrome Web Store o se un amministratore di dominio lo ha installato per tutti gli utenti).
getOAuthToken()StringOttieni il token di accesso OAuth 2.0 per l'utente efficace.
getProjectTriggers()Trigger[]Recupera tutti i trigger installabili associati al progetto e all'utente corrente.
getScriptId()StringVisualizza l'ID univoco del progetto di script.
getService()ServiceRecupera un oggetto utilizzato per controllare la pubblicazione dello script come app web.
getUserTriggers(document)Trigger[]Recupera 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 modulo fornito, solo per questo script o solo 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()voidNon convalida l'autorizzazione concessa all'utente effettivo per eseguire lo script corrente.
newStateToken()StateTokenBuilderCrea un generatore di un token di stato che può essere utilizzato in un'API di callback (come un flusso OAuth).
newTrigger(functionName)TriggerBuilderAvvia il processo di creazione di un trigger installabile che, quando attivato, chiama una funzione specifica.

Documentazione dettagliata

deleteTrigger(trigger)

Rimuove l'attivatore 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
triggerTriggerIl trigger 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)

Visualizza un oggetto utilizzato per determinare se l'utente deve autorizzare questo script a utilizzare uno o più servizi e per fornire l'URL per una finestra di dialogo di autorizzazione. Se lo script è pubblicato come componente aggiuntivo che utilizza attivatori 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 di 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 cui vengono richieste le informazioni di 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

Andata e ritorno

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

getIdentityToken()

Recupera un token di identità OpenID Connect per l'utente efficace se l'ambito openid è stato concesso. Questo ambito non è incluso per impostazione predefinita ed è necessario aggiungerlo come ambito esplicito nel file manifest per richiederlo. 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 token web JSON (JWT) codificato e deve essere decodificato per estrarre le informazioni da questo token. Gli esempi che seguono mostrano come decodificare il token ed estrarre l'ID 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 di OpenID Connect per l'elenco completo dei campi restituiti (rivendicazioni).

Andata e ritorno

String: il token di identità, se disponibile, altrimenti null.

getInstallationSource()

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

Andata e ritorno

InstallationSource: l'origine dell'installazione.

getOAuthToken()

Ottieni il token di accesso OAuth 2.0 per l'utente efficace. Se gli ambiti OAuth degli script sono sufficienti per autorizzare un'altra API Google che normalmente richiede il proprio flusso OAuth (come Selettore Google), gli script possono ignorare la seconda richiesta di autorizzazione passando questo token. Il token scade dopo un certo periodo di tempo (almeno qualche minuto); gli script devono 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 di cui lo script ha attualmente bisogno. Gli ambiti che in precedenza erano autorizzati, ma che non sono più utilizzati dallo script non sono inclusi nel token restituito. Se sono necessari ulteriori ambiti OAuth oltre i requisiti dello script stesso, questi possono essere specificati nel file manifest dello script.

Andata e ritorno

String: 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.');

Andata e ritorno

Trigger[]: un array degli attivatori correnti dell'utente 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()

Visualizza 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 la chiave del progetto era fornita in precedenza.

Andata e ritorno

String: l'ID del progetto di script.

getService()

Recupera un oggetto utilizzato per controllare la pubblicazione dello script come app web. 

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

Andata e ritorno

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

getUserTriggers(document)

Recupera 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 i trigger 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.

Andata e ritorno

Trigger[]: un 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 modulo fornito, solo per questo script o solo componente aggiuntivo. Questo metodo non può essere utilizzato per visualizzare i trigger 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 potrebbe contenere attivatori installabili.

Andata e ritorno

Trigger[]: un 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 i trigger 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 potrebbe contenere attivatori installabili.

Andata e ritorno

Trigger[]: un 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()

Non convalida l'autorizzazione concessa all'utente effettivo per eseguire lo script corrente. Utilizzato per invalidare qualsiasi autorizzazione per lo script corrente. Questa funzione è 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 seguito, devi revocare qualsiasi autorizzazione concessa dallo script, in modo che l'utente possa visualizzare nuovamente la finestra di dialogo dell'autorizzazione. 

ScriptApp.invalidateAuth();

Genera

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

newStateToken()

Crea un generatore di un token di stato che può essere utilizzato in un'API di callback (come 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 passato direttamente all'endpoint di autorizzazione (non come parte dell'URL di callback), quindi l'endpoint di autorizzazione lo trasmette 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 per autorizzare 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 sopra riportato (ritornato a http://script.google.com/...) fa sì che la richiesta del browser venga /usercallback, che richiama il metodo specificato da StateTokenBuilder.withMethod(method).

Andata e ritorno

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

newTrigger(functionName)

Avvia il processo di creazione di un trigger installabile che, quando attivato, chiama una funzione specifica. 

// 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 il trigger. Puoi utilizzare funzioni delle librerie incluse, ad esempio Library.libFunction1.

Andata e ritorno

TriggerBuilder: un oggetto utilizzato per continuare il processo di creazione del 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