Centralizzare le funzioni in una Libreria in Google Apps Script

Una libreria è un progetto di Google Apps Script creato con lo scopo di centralizzare funzioni utili al fine di poterle richiamare da altri script.

VANTAGGI
L'evidente vantaggio di non dover scrivere, o inserire, ogni volta le stesse funzioni in ogni script in cui se ne ha bisogno è quello di rendere il codice più snello, più facilmente manutenibile e velocizzare la realizzazione delle proprie applicazioni.

SVANTAGGI
Come indicato nella documentazione ufficiale, uno degli accorgimenti per migliorare le prestazioni degli script è proprio quello di evitare l'uso delle librerie in quanto partecipano negativamente alla velocità di esecuzione degli script. In particolar modo sono sconsigliate laddove la velocità è un elemento fondamentale, come nelle Add-on.

Per poter includere una libreria all'interno di un progetto Apps Script è essenziale:

- Avere accesso almeno in lettura alla libreria (altrimenti si riceverà un errore di permessi nel momento in cui si tenta di aggiungerla al progetto);
- Conoscere l'ID script della libreria (disponibile in File -> Proprietà del progetto).

L'utilizzo di una libreria è relativamente semplice, con i dovuti accorgimenti nel creare funzioni adeguatamente parametrizzate e con pochi passaggi di implementazione è possibile crearsi una collezione di entità di base pronte per l'uso.

Ci sono alcune best practices che conviene prendere in considerazione quando si scrive una libreria:

- Scegliere un nome rappresentativo per il progetto in quanto verrà utilizzato come identificativo predefinito, questa prassi è molto utile nel caso la libreria venga resa pubblica per l'utilizzo da parte di altri sviluppatori;
- Se vogliamo rendere private alcune funzioni all'interno della libreria, ovvero non accessibili da script esterni, basterà terminare il nome della funzione con un underscore, ad esempio: myFunction_();
- Se vogliamo attivare il completamento automatico dell'editor di script quando si richiamano le funzioni della libreria è necessario dotare ciascuna funzione di descrizione ed informazione sui vari parametri che si traduce in una parte di codice commentata da inserire al di sopra delle funzioni stessi. Di seguito un esempio di questa notazione stile JSDoc (dove solo i parametri @param e @return sono supportati in Apps Script), un altro esempio si trova invece nell'articolo 'Funzioni personalizzate in Google Sheets con Google Apps Script':

/**
 * Restituisce la regione
 *
 * @param {country} il paese nel formato standard ISO 3166-1 alpha-2
 * @param {zip} il codice di aviamento postale
 * @return {string} the result of the exponential calculation
 */
function getRegionByZip(country, zip) {
  var res = getGeolocByZip_(country, zip);
  return res.places[0].state;
}

Vediamo con un caso pratico come utilizzare una libreria di funzioni Apps Script.
Nel caso specifico l'intenzione è quella di creare una libreria contenente una serie di funzioni che mi permettano di georeferenziare un codice di aviamento postale per ottenere in risposta l'informazione puntuale di latitudine e longitudine, regione, ecc... Allo scopo mi sono avvalso di un'API gratuita per il recupero di tali dati, descritta nell'articolo 'Georeferenziare un CAP con una chiamata in GET in Google Apps Script'.

Come detto ad inizio articolo, una libreria è un progetto Apps Script pertanto come primo passo è necessario creare un nuovo progetto che chiamerò, per seguire i consigli delle best practices, 'GeoZipLibrary' all'interno del quale ho inserito una funzione privata (getGeolocByZip_) che effettua la chiamata all'API e che può essere interrogata solo dall'interno della libreria da parte delle funzioni ad uso esterno chiamate getLngLatByZip e getRegionByZip, Fig. 1:

Fig. 1 - Esempio di una Libreria in Apps Script gestita come da best practices

Per poter essere inclusa in un altro script, una libreria, deve contenere una versione salvata (che rappresenta un'istantanea del progetto) pertanto, una volta inserite in essa le opportune funzioni è necessario, nel relativo editor di script, recarsi alla voce di menu 'File -> Gestisci versioni...' e nella finestra che si aprirà inserire una descrizione (opzionale) come nota di cosa è stato modificato/aggiunto rispetto ad una eventuale versione precedente e cliccare su 'Salva una nuova versione', Fig. 2:

Fig. 2 - Versioni salvata del progetto utilizzabili in altri script come libreria

Una nota sulle versioni in quanto, come è facile intuire, tramite l'icona della 'x' è possibile eliminare una versione dall'elenco ma è bene sapere che una versione eliminata non può più essere recuperata.

Queste e molte altre informazioni sulle Librerie in Google Apps Script continuano nel mio libro "Punta in alto con... Google Apps Script":

Fig. 3 - Il libro in italiano - Punta in alto con... Google Apps Script - pag 194 e 195

Troverai altre informazioni sulle Librerie di Apps Script come:

- la gestione delle Proprietà del progetto;
- l'uso dell'interfaccia per la gestione delle versioni delle Librerie;
- l'importanza dell'identificatore;
- collegamento delle librerie;
- richiamo di funzioni centralizzate;
- funzioni pubbliche e funzioni private;
- ponderazione dell'ottimizzazione degli script;
- tutta una serie di informazioni utili con immagini chiare ed esemplificative.

...E QUESTO È SOLO QUANTO RIFERITO ALL'USO DELLE LIBRERIE IN APPS SCRIPT!

ACQUISTA ORA IL LIBRO 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!