Il file Manifest in Google Apps Script: cos'è e come gestirlo

Dal 24 ottobre 2017, come indicato nelle note di rilascio relative alle modifiche principali apportati ad Apps Script da parte di Google (Release Notes: 2017), è stata data la possibilità di visualizzare e modificare in modo esplicito i manifest dei progetti Apps Script.
Questo tipo di file permette di avere un controllo più diretto delle proprietà del progetto consentendo agli sviluppatori di specificare dipendenze come librerie e servizi avanzati, di lavorare con ambiti più selettivi, di controllare le versioni delle librerie, ecc...

La documentazione ufficiale di Google Apps Script descrive il manifest come, un particolare file JSON che specifica le informazioni di base sul progetto di cui Apps Script necessita per poter eseguire lo script correttamente.

Da premettere che Apps Script crea e aggiorna automaticamente il manifest del progetto durante le varie lavorazioni e modifiche apportate nell'editor, ovvero se dall'interfaccia si aggiunge una libreria oppure si abilita un servizio avanzato, il manifest di conseguenza, senza bisogno di interventi da parte dello sviluppatore, si aggiorna in maniera autonoma e trasparente.
Allo stesso modo eliminare o modificare manualmente porzioni del manifest significa andare ad agire sulle impostazioni effettuate da interfaccia che, dopo il salvataggio, risulteranno alterate (una modifica non ponderata sul file manifest può compromettere il corretto funzionamento dello script).

Fortunatamente, nella maggior parte dei casi non si ha mai la necessità di visualizzare ne tantomeno modificare direttamente il manifest, tuttavia, esistono determinate situazioni dove farlo può essere utile se non addirittura richiesto.
A tal proposito è bene sapere che i file manifest possono anche essere visualizzati e modificati, oltre che manualmente, tramite le API di Drive, utile se si desidera apportare modifiche programmatiche a un progetto di script.

Per visualizzare il manifest, basterà selezionare la voce di menu 'Visualizza -> Mostra il file manifest', come evidenziato in Fig. 1, si aprirà nell'editor di script un file chiamato appsscript.json contenente le informazioni di progetto:

Fig. 1 - Percorso nel menu dell'editor di script per aprire il file manifest

Come indicato nella documentazione ufficiale, il manifest ha una struttura JSON (Manifest structure) di questo tipo:

{
  "timeZone": string,
  "oauthScopes": [
    string
  ],
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": string,
        "serviceId": string,
        "version": string,
      }
    ],
    "libraries": [
      {
        "userSymbol": string,
        "libraryId": string,
        "version": string,
        "developmentMode": boolean,
      }
    ]
  },
  "exceptionLogging": string,
  "webapp": {
    "access": string,
    "executeAs": string,
  },
  "executionApi": {
    "access": string,
  },
  "urlFetchWhitelist": [
    string
  ],
  "gmail": gmail Resource
}

Un progetto appena creato avrà tuttavia solo alcune proprietà: timeZone, dependencies (con valore vuoto) ed exceptionLogging, come mostrato nel codice seguente:

{
  "timeZone": "Europe/Paris",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER"
}

Comprendere a cosa si riferiscono le varie proprietà e cosa comporta una loro modifica può essere utile per l'ottenimento di script più performanti a seconda delle proprie esigenze.
Di seguito una breve analisi delle varie proprietà disponibili:

timeZone (fuso orario)
La proprietà timeZone viene utilizzata per impostare il fuso orario dello script. I fusi orari sono registrati come valori ZoneId (es: Europe/Paris).
L'impostazione di un fuso orario dello script è utile, ad esempio, per impostare l'esecuzione di script tramite trigger basati sul tempo al fine di attivarli al momento opportuno (per una lista delle ZoneId fare riferimento a questo GitHub di Mashe Hawksey: appscriptzoneids.csv).

oauthScopes (ambiti)
Gli ambiti fanno parte del flusso di autorizzazione di Google (oauthScopes) e tramite la loro gestione è possibile limitare un ambito o aggiungerlo, tuttavia è consigliato di utilizzare l'ambito rilevato automaticamente dallo script per evitare sovrascritture degli stessi, ad esempio importando librerie, rendendo il codice non funzionante come aspettato.
Un esempio di implementazione di un oauthScopes nel manifest (per prendere visione della sintassi) è il seguente:

"oauthScopes": [
     "https://www.googleapis.com/auth/script.external_request",
     "https://www.googleapis.com/auth/script.scriptapp",
     "https://www.googleapis.com/auth/drive",
     "https://www.googleapis.com/auth/drive.scripts"
]

Queste e molte altre informazioni sul file Manifest di Google Apps Script continuano nel mio libro "Punta in alto con... Google Apps Script":

Fig. 2 - Il libro in italiano - Punta in alto con... Google Apps Script - pag 90 e 91

Troverai altre informazioni sul file Manifest di Apps Script come:

- urlFetchWhitelist (lista bianca degli indirizzi web);
- dependencies (dipendenze);
- webApp (script distribuito come applicazione web);
- executionAPI (script distribuito come API eseguibile);
- gmail;
- ed altre informazioni sulla manipolazione del manifest.

...E QUESTO È SOLO QUANTO RIFERITO A QUESTO PARTICOLARE FILE DI APPS SCRIPT!

ACQUISTA IL LIBRO ORA SU AMAZON:

Se sei pronto a diventare un esperto nella programmazione in Google Apps Script non posso fare altro che augurarti una buona lettura e soprattutto... Buon divertimento!

DISCLAIMER:
Il presente articolo riferito al file Manifest è stato redatto sulla base di un video presente su Youtube della 'Totally UnScripted' (una community di Google Apps Script) che può essere visualizzato al seguente link 'TU14 Highlight: Google Apps Script Manifest Files'.
Ovviamente, essendo la gestione del manifest un aspetto in rapido e continuo sviluppo, le informazioni ad oggi riportate potrebbero non risultare più coerenti o non completamente trattate con i contenuti e le caratteristiche riferite al manifest nei prossimi eventuali rilasci da parte di Google.