Javascript, HTML, CSS e... !
0 commenti

Maggiore controllo sulle proprietà del progetto

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:



percorso nel menu dell'editor di script per aprire il file manifest

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"
]

urlFetchWhitelist (lista bianca degli indirizzi web)
La specifica di un urlFetchWhitelist nel file manifest limita gli URL a cui il progetto di script può accedere con il servizio UrlFetch.
Un esempio:

  "urlFetchWhitelist": [
    "https://www.appsscript.it/"
  ],

Specificando un URL in questa proprietà e provando a richiamare tramite UrlFetch un altro indirizzo web otterremo un messaggio di errore: 'L'invio della richiesta a http://www.michelepisani.it/ non è riuscito perché l'URL non è stato autorizzato nel manifest dello script', Fig. 2:



invio della richiesta non riuscito perché l'url non è stato autorizzato nel manifest dello script

Fig. 2 - Messaggio di errore: L'invio della richiesta a http://www.michelepisani.it/ non è riuscito perché l'URL non è stato autorizzato nel manifest dello script


Altri messaggi di errore dell'interfaccia, restituiti subito al momento del salvataggio nel caso di inserimento di un URL in white list, si hanno se si inserisce l'indirizzo del dominio senza lo slash finale, ad esempio "https://www.appsscript.it" (L'URL non può avere un percorso vuoto) oppure con un protocollo in http (Gli URL devono utilizzare lo schema HTTPS). Per maggiori informazioni sul formato degli Whitelisted URLs rimando alla documentazione ufficiale.

dependencies (dipendenze)
Ci sono due tipologie di dipendeze che possono essere aggiunte al manifest, le enabledAdvancedServices (per l'abilitazione dei servizi avanzati) e le libraries (per l'inserimento delle librerie).
Un esempio:

  "dependencies": {
    "enabledAdvancedServices": [{
      "userSymbol": "Slides",
      "serviceId": "slides",
      "version": "v1"
    }, {
      "userSymbol": "Sheets",
      "serviceId": "sheets",
      "version": "v4"
    }],
    "libraries": [{
      "userSymbol": "FirebaseApp",
      "libraryId": "1hguuh4Zx72XVC1Zldm_vTtcUUKUA6iBUOoGnJUWLfqDWx5WlOJHqYkrt",
      "version": "26"
    }]
  },

Nel caso specifico sono stati abilitati dall'editor di script i servizi avanzati di Google Slides e Google Sheets (da 'Risorse -> Servizi avanzati di Google ...') e la libreria di Firebase (da 'Risorse -> Librerie...').
Per quanto riguarda i Servizi Avanzati di Google, considerando che l'abilitazione degli stessi deve avvenire anche nella Console API Google (come mostrato nel tutorial 'Abilitare l'uso delle API dei Servizi Avanzati nei progetti in Google Apps Script'), una integrazione tramite il manifest (così come solo da interfaccia di script) non attiverà effettivamente il servizio. Quello che può essere tuttavia gestito dal manifest direttamente è la versione del servizio (version) ed il nome di riferimento nello script, detto anche identificatore (userSymbol).
Le librerie invece possono essere aggiunte direttamente da codice, un esempio di installazione di una libreria tramite la gestione del manifest da codice, preso dallo script demo 'Install Library Demo (PicasaApp)', è il seguente:

// Installa la libreria di Picasa nello script
function installPicasaApp(scriptId, fileDetails){
  try {
    var MANIFEST = ManifestsApp.setProjectId(scriptId);
    var libs = MANIFEST.getLibraries();
    // if the library is already added remove first
    if (libs && libExists_(libs, 'PicasaApp')) {
      MANIFEST.uninstallLibrary('PicasaApp');
    }
    // add library with the version you require
    var result = MANIFEST.installLibrary('PicasaApp', '1RHjbqdEN-WvQxqSFr6hdtECfIqZlEEyCfrxvF4UKnKeVPnRX-dyg0dS7', 22);
    return fileDetails;
  } catch(e){
    return e;
  }
}

// Verifica se la libreria è già presente nel manifest
function libExists_(lib, libName) {
  return lib.some(function(el) {
    return el.userSymbol === libName;
  }); 
}

webApp (script distribuito come applicazione web)
Nel momento in cui si distribuisce una Web app, il livello di accesso (access) e la modalità di esecuzione (executeAs) vengono scritte automaticamente nel manifest.
La porzione di manifest seguente mostra un livello di accesso alla Web app di tipo ANYONE e la modalità di esecuzione della stessa come USER_ACCESSING:

  "webapp": {
    "access": "ANYONE",
    "executeAs": "USER_ACCESSING"
  },

La configurazione da interfaccia che rispecchia la situazione di cui sopra è la seguente, Fig. 3:



esempio di autorizzazioni dello script per la sua distribuzione come web app

Fig. 3 - Esempio di autorizzazioni dello script per la sua distribuzione come Web app


executionAPI (script distribuito come API eseguibile)
Stesso concetto della proprietà webApp, in questo caso però è solo presente il livello di accesso:

  "executionApi": {
    "access": "ANYONE",
  },

gmail
Questa parte è specifica per lo sviluppo di componenti aggiuntivi (add-on) per Gmail tramite Apps Script.
Nel manifest viene definito come il componente aggiuntivo dovrà apparire e si dovrà comportare nel progetto Apps Script, ad esempio le informazioni del nome, dell'URL del logo, dei colori, ecc...
Un esempio preso dalla documentazione ufficiale relativa al Manifest per le add-on Gmail, dove rimando per eventuali approfondimenti, è il seguente:

  "gmail": {
    "name": "My Gmail Add-on",
    "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
    "primaryColor": "#4285F4",
    "secondaryColor": "#00BCD4",
    "authorizationCheckFunction": "get3PAuthorizationUrls",
    "contextualTriggers": [{
      "unconditional": {},
      "onTriggerFunction": "buildAddOn"
    }],

Sulla base di queste informazioni, e come anticipato nella precedente porzione di codice relativa all'aggiunta programmatica di una libreria, il file manifest può essere gestito anche tramite le Drive API.
La manipolazione del manifest, avendo una struttura di tipo JSON, è relativamente semplice tuttavia esiste una libreria, chiamata ManifestsApp, creata da Kanshi Tanaike, utilizzabile sia per i progetti standalone che per gli script associati al contenitore (Sheet, Document o Form). Nel link appena proposto sono presenti le linee guida all'installazione e all'uso della libreria.

DISCLAIMER:
Il presente articolo è 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.

Tags

Michele Pisani

Michele Pisani

Sviluppatore Javascript ed esperto in Digital Analytics

L'esperienza nel settore Digital Analytics unita ad anni di sviluppo in Javascript ha trovato la massima espressione in Google Apps Script che mi ha permesso, con estrema facilità e poche righe di codice, di realizzare potenti applicazioni interattive e processi automatizzati integrati con i prodotti della G Suite.

Come contattarmi
scrivi un commento

0 Commenti

Non ci sono commenti

Nessuno ha ancora commentato questo articolo, fallo tu per primo!

scrivi un commento

Scrivi un commento

Il tuo indirizzo email non sarà pubblicato.I campi contrassegnati da un * sono obbligatori
Puoi utilizzare i seguenti tag nei commenti:
[bold]testo[/bold] se vuoi evidenziare un testo con il grassetto[code]function helloworld() { }[/code] se vuoi pubblicare una porzione di codice[url]http://www.appsscript.it[/url] se devi riferirti ad un indirizzo web