Interrogare una funzione in Google Apps Script da Remoto con le Execution API

Allo stesso modo delle interfacce utente che ci consentono di interagire con un'applicazione, le API (Application Programming Interface) consentono alle applicazioni di interagire con altre applicazioni.

Le ragioni per cui le applicazioni possono utilizzare le API sono molteplici. Da casi relativamente avanzati che possono richiedere un sistema di autenticazione, come ad esempio, in un ecommerce per il recupero delle informazioni dai sistemi di logistica dei corrieri per fornire al cliente aggiornamenti sullo stato e sulla posizione della propria merce, oppure in un sito di un'operatore turistico accreditato per creare un proprio servizio di prenotazione voli collegandosi al webservice messo a disposizione dalla compagnia aerea per recuperare orari, disponibilità e costi, fino a casi più semplici come quello per collegarsi in modo diretto ad un servizio web al fine di 'Georeferenziare un CAP con una chiamata in GET in Google Apps Script' oppure 'Creare un servizio Whois con una chiamata in GET in Google Apps Script'.

Tramite le API di Apps Script, nello specifico con il metodo scripts.run, è possibile eseguire in modalità remota una funzione Apps Script specificata, al fine di interrogare tale funzione presente all'interno di un progetto Apps Script da un'applicazione esterna chiamante e ricevere in quest'ultima una risposta.

Per fare un esempio di come procedere alla creazione di un'API in Google Apps Script, ho preso come riferimento la semplice funzione presente direttamente nella documentazione ufficiale (Executing Functions using the Apps Script API) che non fa altro che restituire la lista delle cartelle presenti nella root del proprio Drive mostrandone il relativo nome e l'ID.

In un caso pratico d'uso basterà sostituirla con la o le funzioni utili ai propri scopi:

function getFoldersUnderRoot() {
  var root = DriveApp.getRootFolder();
  var folders = root.getFolders();
  var folderSet = {};
  while (folders.hasNext()) {
    var folder = folders.next();
    folderSet[folder.getId()] = folder.getName();
  }
  return folderSet;
}

Utilizzerò a scopo illustrativo Postman per interrogare l'API, tramite autenticazione, simulando così una chiamata da un servizio remoto (nella documentazione ufficiale indicata sopra sono presenti alcuni esempi di interrogazione dell'API di Apps Script da servizi in Android, in PHP, ecc... che fanno uso della Google API Client Libraries).

Nel mio caso la root di Drive si presenta come nell'immagine seguente, Fig. 1:

Fig. 1 - Esempio del contenuto della root di Drive

Per avere un'idea di cosa tale funzione restituirà, riporto di seguito (Fig. 2) il risultato presente nel Log dopo aver provato ad eseguirla direttamente dall'editor di script di Apps Script:

Fig. 2 - Esempio di un risultato della Lista di Nomi e ID delle cartelle nella root di Drive

Dopo aver aperto un nuovo file di script e quindi creato un nuovo progetto Apps Script con la funzione di interesse, al fine di creare un'API, è necessario come primo passaggio selezionare la voce di menu 'Pubblica -> Distribuisci come API eseguibile...'.
La prima volta si aprirà una finestra dove è richiesto l'inserimento della versione (default '1') e di chi ha accesso allo script ('solo io' o 'chiunque'), definiti questi valori e cliccato su 'Distribuisci' comparirà una seconda finestra dove viene mostrato, oltre alle impostazioni appena definite, l'ID dell'API attuale (Fig. 3):

Fig. 3 - Finestra dettagli per la distribuzione di un'API eseguibile in Apps Script

Il passo successivo è quello di recarsi nella Google Console del progetto per abilitare le Google Apps Script API, Fig. 4 (per verificare come poter accedere direttamente alla Console di progetto e abilitare l'API fare riferimento all'articolo 'Abilitare l'uso delle API dei Servizi Avanzati nei progetti in Google Apps Script'):

Fig. 4 - Google Console del progetto per l'abilitazione delle Google Apps Script API

Sempre nel pannello della Console di progetto spostarsi nella voce di menu 'Credenziali', dopodiché espandere il combobox 'Crea credenziali' per andare a selezionare ID Client OAuth per far sì che la nostra API richieda l'approvazione dell'utente affinché l'app possa accedere ai suoi dati, Fig. 5:

Fig. 4 - Creazione credenziali di tipo ID Client OAuth nella Google Console del progetto Google Apps Script API

Verrà ora richiesto il tipo di applicazione, nel mio caso seleziono 'Applicazione web' e come nome inserisco semplicemente 'Client web', Fig. 5:

Fig. 5 - Fase 2 per la creazione credenziali nella Google Console del progetto Google Apps Script API

Viene creato così un ID Client ed un Client secret che serviranno successivamente per generare il token di autenticazione, Fig. 6:

Fig. 6 - ID client e Client secret nella Google Console del progetto Google Apps Script API

Assicurarsi che tra gli URL di reindirizzamento autorizzati sia presente: https://script.google.com/oauthcallback, altrimenti inserirlo.

Nel caso dell'esempio, utilizzando Postman, ho dovuto inserire anche il relativo URL di reindirizzamento per far sì che l'operazione di test da tale strumento possa andare a buon fine, ovvero: https://www.getpostman.com/oauth2/callback

Adesso abbiamo a disposizione tutti i tasselli del puzzle, servirà solo metterli insieme correttamente...

Eseguire Postman ed inserire il seguente URL (vedere codice sotto) nell'apposità barra degli indirizzi (Fig. 7 al punto 1), assicurandosi di selezionare POST come metodo di chiamata e di sostituire nell'url, il testo 'TUO_API_ID' con l'ID dell'API attuale (quello visto in Fig. 3):

https://script.googleapis.com/v1/scripts/TUO_API_ID:run

Cliccare su 'Params' presente sulla sinistra del tasto 'Send' per espandere i campi evidenziati in Fig. 7 al punto 2 dove dovrà essere inserito come chiave il termine 'function' e come valore il nome della funzione che si intende interrogare:

Fig. 7 - Esempio di impostazioni in Postman

Immediatamente sotto alla definizione della funziona appena descritta si presenta la parte relativa alle autorizzazioni, dove, dopo aver selezionato nella parte sinistra il tipo, alla voce TYPE, di autorizzazioni (OAuth 2.0) e come passare tale informazione (Request Headers), sarà opportuno creare un token di accesso (Fig. 7 al punto 3) cliccando sul relativo bottone.

Si aprirà una finestra, Fig. 8, con la richiesta di immissione delle informazioni necessarie per la generazione di un token di accesso, che nello specifico sono le seguenti:

Token Name: il nome da attribuire al token (può essere una stringa qualsiasi)
Grant Type: il tipo di identificazione, nel caso specifico 'Authorization Code'
Callback URL: l'URL di callback dove verrà effettuat il redirect una volta che l'applicazione è stata autorizzata, nel caso specifico 'https://script.google.com/oauthcallback'
Auth URL: l'endpoint sul server per recuperare il codice di autorizzazione, 'https://accounts.google.com/o/oauth2/auth'
Access Token URL: l'endpoint sul server per ottenbere un token di accesso, 'https://accounts.google.com/o/oauth2/token'
Client ID: l'identificativo presente nelle credenziali generate precedentemente nella Google Console del progetto
Client secret: la chiave presente nelle credenziali generate precedentemente nella Google Console del progetto
Scope: l'ambito della richiesta di accesso, 'https://www.googleapis.com/auth/drive'
State: un valore utilizzato per prevenire le richieste cross-site, non necessario in questo contesto
Client Authentication: Send as Basic Auth Header

Fig. 8 - Esempio di richiesta di un Token di accesso in Postman

Confermando i dati inseriti, ovvero al clic su 'Request Token', apparirà la schermata di login di Google prima di mostrare una finestra con il nome di accesso pronto per essere utilizzato, Fig. 9:

Fig. 9 - Token di Autenticazione ottenuto in Postman

Confermando con il clic su 'Use Token' si chiuderà la relativa finestra e sarà possibile a questo punto cliccare su 'Send' per effettuare la chiamata in remoto alla nostra funzione in Apps Script.

Se tutto è andato a buon fine verrà mostrato il JSON con la risposta nella parte inferiore di Postman, come mostrato in Fig. 7 al punto 4 e come riportato per comodità di seguito, Fig. 10:

Fig. 10 - Esempio di risposta ad una chiamata in remoto con Postman ad una funzione in Apps Script

Diventa facile verificare che il contenuto del JSON risultate dalla chiamata all'API di Apps Script è lo stesso visualizzato a inizio articolo nel Log dell'editor di script, allo scopo di confermare l'effettivo funzionamento della procedura.

Un altro modo, più facile e veloce, per creare una API o un web service con Google Apps Script si basa sulla pubblicazione dello script come applicazione web ed è presente nell'articolo 'Creare un Web Service o una RESTful API con Google Apps Script'.