Google Apps Script e Gemini API: estrazione dati intelligente

L’inserimento manuale dei dati è il nemico della produttività. Se il tuo team si affida all’estrazione di dati da email operative, come fatture, conferme di prenotazione o moduli di feedback dei clienti, conosci bene l’incubo dei metodi di parsing tradizionali. 

Storicamente, gli sviluppatori hanno fatto affidamento sulle espressioni regolari (Regex) per estrarre dettagli come numeri di fattura o importi di addebito. Ma le Regex sono estremamente fragili: al primo cambio del template dell’email da parte di un fornitore o all’aggiunta di un’interruzione di riga casuale, l’intero parser si rompe in silenzio.

In questo tutorial ti mostro come creare una pipeline completamente automatizzata e headless che risolve questo problema usando l’IA generativa. Scriveremo uno script leggero che legge i messaggi non letti di Gmail, passa il testo non strutturato alla Gemini API per un’estrazione intelligente e registra i dati JSON perfettamente strutturati direttamente in un Foglio Google.

Prerequisiti:

• Un account Google
• Conoscenza di base di JavaScript (Google Apps Script)
• Una chiave API di Gemini

Che cos’è Google Apps Script?

Google Apps Script è una piattaforma di sviluppo cloud-based e rapida, basata su JavaScript, che ti permette di automatizzare, personalizzare ed estendere le applicazioni Google Workspace come Documenti, Fogli, Presentazioni e altro. 

Poiché la piattaforma gira direttamente sui server di Google, non c’è bisogno di installare software, configurare ambienti locali o gestire infrastrutture. 

Apps Script offre a sviluppatori e low-code developer la possibilità di interagire in modo programmatico con gli strumenti di Google Workspace come Documenti, Fogli, Presentazioni, Drive e altro. Puoi creare ed eseguire automazioni tramite menu personalizzati, clic su pulsanti o pianificazioni temporali, oppure usare il servizio per creare e pubblicare componenti aggiuntivi sul Google Workspace Marketplace.

Come funziona Google Apps Script

Google Apps Script astrae il lavoro pesante della configurazione backend e dell’autenticazione API, permettendoti di concentrarti direttamente su logica e dati. Lo fa tramite diverse funzionalità:

• Editor cloud-native: scrivi, fai debug e distribuisci il tuo codice JavaScript interamente in un IDE web integrato direttamente nel browser.
• Servizi integrati: invece di lottare con OAuth e chiamate API complesse, usi oggetti globali pronti all’uso (come SpreadsheetApp, MailApp o DriveApp) per interagire nativamente con i servizi Google.
• Trigger event-driven: gli script possono essere eseguiti manualmente tramite pulsanti di menu personalizzati, oppure pianificati per l’esecuzione automatica con trigger basati sul tempo (ad esempio ogni mezzanotte) e trigger basati su eventi (ad esempio quando un utente invia un modulo Google).

Architettura di Google Apps Script: pipeline da Gmail a Sheets

Prima di scrivere lo script, mappiamo il flusso dei dati attraverso questa pipeline. L’architettura si basa su quattro componenti distinti che lavorano insieme:

• Gmail (Sorgente): il processo inizia interrogando la tua casella di posta usando operatori di ricerca standard (come is:unread label:invoices). Lo script isola i thread email corretti ed estrae sia il corpo in testo semplice sia eventuali file PDF allegati.
• Apps Script (Compute): funge da livello di orchestrazione. Scorre i thread non letti, formatta gli allegati in dati base64 e gestisce la logica per la segnalazione degli errori e l’elaborazione in batch.
• Gemini API (Motore di trasformazione): Apps Script invia un payload multimodale (il testo dell’email più i PDF) al modello Gemini 2.5 Flash. Passando uno schema di risposta JSON rigido nella chiamata API, forziamo il modello a estrarre valori esatti come fornitore, importo totale e valuta, invece di generare testo conversazionale.
• Google Sheets (Destinazione): una volta che Gemini restituisce il JSON strutturato, Apps Script analizza i risultati, li raggruppa in un singolo array e inserisce i dati in batch nella successiva riga vuota del foglio di lavoro attivo usando setValues().

Perché usare Google Apps Script come livello di calcolo per questo progetto? 

Il vantaggio principale è l’eliminazione completa dell’overhead infrastrutturale. Non serve alcun provisioning di server e non devi configurare container Docker o impostare flussi OAuth complicati solo per leggere le tue email o scrivere in un foglio di calcolo. 

Poiché Apps Script si integra nativamente con servizi come GmailApp e SpreadsheetApp, Google gestisce l’autenticazione internamente. Devi solo scrivere il codice e collegare gli endpoint.

Passaggio 1: prepara il tuo ambiente Google Apps Script

Prima di scrivere il codice, dobbiamo preparare le dipendenze esterne. Questo include ottenere l’accesso alla Gemini API, creare il foglio di destinazione e configurare la posta in arrivo di Gmail per etichettare correttamente le fatture in arrivo.

Generare la chiave API di Gemini

Per alimentare la nostra estrazione intelligente dei dati, ci serve l’accesso alla Gemini API.

1. Vai su Google AI Studio ed esegui l’accesso con il tuo account Google.
2. Nel menu di navigazione a sinistra, fai clic su Get API key.
3. Fai clic sul pulsante Create API key. Puoi scegliere di creare questa chiave in un progetto Google Cloud esistente o lasciare che AI Studio ne crei uno nuovo per te.
4. Copia la stringa generata. 

Buona prassi di sicurezza: non perdere questa chiave e, soprattutto, non pensare di inserirla in chiaro nel tuo codice. Tienila negli appunti o in un notepad sicuro per ora; nel prossimo passaggio la metteremo al sicuro all’interno del nostro ambiente Apps Script.

Preparare il Foglio Google e mettere in sicurezza la chiave

Ci serve un posto dove archiviare i dati estratti. Questo foglio fungerà anche da base di lancio per il nostro script di automazione.

1. Imposta le intestazioni del database Crea un nuovo Foglio Google vuoto. Nella prima riga, crea le seguenti intestazioni di colonna per allinearle allo schema JSON che definiremo nello script:

• Date
• Vendor
• Invoice Number
• Total Amount
• Currency
• Items Summary
• Email Link

Blocca la prima riga così le intestazioni restano visibili man mano che i dati crescono.

2. Accedi ad Apps Script e archivia la chiave API Ora che il Foglio esiste, possiamo aprire l’editor di Apps Script direttamente da lì. Questo collega automaticamente il nostro codice a questo specifico foglio di calcolo.

1. Nel tuo Foglio Google, fai clic su Estensioni > Apps Script dal menu in alto.
2. Quando si apre l’editor, guarda la barra laterale sinistra e fai clic sull’icona a ingranaggio per aprire le Impostazioni progetto.

3. Scorri fino in fondo per trovare la sezione Proprietà script.
4. Fai clic su Aggiungi proprietà script.
5. Nel campo Proprietà, digita esattamente GEMINI_API_KEY.
6. Nel campo Valore, incolla la chiave API che hai copiato da AI Studio in precedenza.
7. Fai clic su Salva proprietà script.

Il codice che scriveremo più avanti ora potrà recuperare in modo sicuro questo valore a runtime senza esporre le tue credenziali.

Passaggio 2: scrivi il codice Google Apps Script

Mentre ti trovi nell’editor di Apps Script, elimina pure qualsiasi codice predefinito. Costruiremo il nostro motore di automazione blocco per blocco.

1. Configurazione e impostazione dell’interfaccia

Iniziamo definendo un oggetto di configurazione globale. È una buona pratica di clean code che raggruppa tutte le variabili hardcoded in un unico posto, così dovrai modificare solo questo blocco iniziale.

Aggiungiamo anche una funzione onOpen(). Questo trigger integrato di Apps Script crea automaticamente un menu personalizzato nel tuo Foglio Google, permettendo agli utenti non tecnici di eseguire lo script manualmente senza aprire l’editor del codice.

const CONFIG = {
 searchQuery: "is:unread label:invoices",
 model: "gemini-2.5-flash",
 adminEmail: Session.getActiveUser().getEmail() // Automatically emails the script owner if it crashes
};

/**
* Creates a custom menu in Google Sheets so non-technical users can run the script manually.
*/
function onOpen() {
 const ui = SpreadsheetApp.getUi();
 ui.createMenu('🤖 AI Automations')
   .addItem('Fetch New Invoices', 'processInvoices')
   .addToUi();
}

2. Impostazione dell’orchestrazione

La funzione processInvoices() funge da orchestratore principale. Inizia recuperando in modo sicuro la tua chiave API dalle Proprietà script che abbiamo impostato in precedenza. 

Poi usa il servizio integrato GmailApp per interrogare la tua casella di posta.

Chiamando GmailApp.search(CONFIG.searchQuery), lo script recupera un array di thread email che corrispondono alla nostra regola is:unread label:invoices. 

Se trova corrispondenze, scorre ogni thread, prende il messaggio più recente, estrae il corpo in testo semplice e isola eventuali PDF allegati.

function processInvoices() {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  if (!apiKey) {
    throw new Error("GEMINI_API_KEY is missing! Please set it in Script Properties.");
  }

  const threads = GmailApp.search(CONFIG.searchQuery);
  if (threads.length === 0) return;

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const batchData = [];
  const processedThreads = [];

3. Elaborare le email e i PDF multimodali

Mentre scorriamo i thread email, prendiamo il messaggio più recente. Tuttavia, le fatture raramente arrivano come testo semplice; quasi sempre sono allegate come PDF. 

Sfruttando Gemini 2.5 Flash, che è nativamente multimodale, il nostro script scorre latestMessage.getAttachments(), rileva eventuali PDF, li converte in una stringa Base64 e li passa direttamente al payload dell’API come inlineData. 

Gemini “legge” visivamente il PDF ed estrae i dati con la stessa facilità con cui legge il testo.

for (let i = 0; i < threads.length; i++) {
   const thread = threads[i];
   const latestMessage = thread.getMessages().pop();
  
   const emailBody = latestMessage.getPlainBody();
   const emailDate = latestMessage.getDate();
   const emailLink = https://mail.google.com/mail/u/0/#inbox/${thread.getId()};
   const attachments = latestMessage.getAttachments();
   try {
     const geminiParts = [];
     geminiParts.push({ text: "Extract invoice details from this email and any attached documents:\n\n" + emailBody });
    
     // Add PDF attachments as base64 to the prompt
     for (const attachment of attachments) {
       if (attachment.getContentType() === "application/pdf") {
         geminiParts.push({
           inlineData: {
             mimeType: "application/pdf",
             data: Utilities.base64Encode(attachment.getBytes())
           }
         });
       }
     }
     // Invoke Gemini API
     const extractedData = callGeminiAPI(apiKey, geminiParts);

4. Inserimento in batch e gestione degli errori

Per ottimizzare le prestazioni, non scriviamo nel foglio di calcolo una riga alla volta. 

Invece, inseriamo i dati JSON estratti in un array (batchData) e li scriviamo tutti in una volta sola alla fine usando setValues().

Nota il blocco try...catch. 

Se Gemini allucina o fallisce su una specifica email, lo script non va in crash completo. Invece, intercetta l’errore in modo elegante e usa MailApp.sendEmail() per avvisare immediatamente l’amministratore, garantendo un’elevata osservabilità.

 // Push to batch array instead of writing one-by-one
     batchData.push([
       emailDate,
       extractedData.vendor || "Unknown Vendor",
       extractedData.invoiceNumber || "N/A",
       extractedData.totalAmount || 0.00,
       extractedData.currency || "USD",
       extractedData.itemsSummary || "N/A",
       emailLink
     ]);
     processedThreads.push(thread);
   } catch (error) {
     MailApp.sendEmail(CONFIG.adminEmail, "🚨 Invoice Pipeline Error", error.toString());
   }
 }
 // Batch Write to Sheets
 if (batchData.length > 0) {
   const lastRow = Math.max(sheet.getLastRow(), 1);
   sheet.getRange(lastRow + 1, 1, batchData.length, batchData[0].length).setValues(batchData);
 }
 // Mark all processed threads as read so they aren't parsed again
 processedThreads.forEach(t => t.markRead());
}

Infine, lo script chiama thread.markRead() su ogni email elaborata. Questo garantisce che alla successiva esecuzione lo script ignori completamente queste email e cerchi solo quelle nuove.

5. La funzione helper della Gemini API (modalità JSON)

Quando si chiamano LLM, gli sviluppatori spesso usano il prompt engineering tipo “Restituisci un blocco JSON”. Tuttavia, i modelli rispondono frequentemente con riempitivi conversazionali (ad es. “Certo, ecco i tuoi dati: [JSON]”), cosa che fa andare in crash i parser a valle.

Impostando responseMimeType: "application/json" e fornendo uno responseSchema rigoroso, forziamo la Gemini REST API a rispondere solo con un oggetto JSON garantito contenente le nostre esatte intestazioni di colonna del foglio di calcolo.

function callGeminiAPI(apiKey, partsArray) {
 const url = https://generativelanguage.googleapis.com/v1beta/models/${CONFIG.model}:generateContent?key=${apiKey};
  const responseSchema = {
   type: "OBJECT",
   properties: {
     vendor: { type: "STRING" },
     invoiceNumber: { type: "STRING" },
     totalAmount: { type: "NUMBER" },
     currency: { type: "STRING" },
     itemsSummary: { type: "STRING" }
   },
   required: ["vendor", "totalAmount"]
 };
  const payload = {
   contents: [{ parts: partsArray }],
   generationConfig: {
     responseMimeType: "application/json",
     responseSchema: responseSchema
   }
 };
  const options = {
   method: "POST",
   contentType: "application/json",
   payload: JSON.stringify(payload),
   muteHttpExceptions: true
 };
  const response = UrlFetchApp.fetch(url, options);
 const jsonResponse = JSON.parse(response.getContentText());
  return JSON.parse(jsonResponse.candidates[0].content.parts[0].text);
}

Passaggio 3: automatizza la tua pipeline Google Apps Script

Il codice è utile solo se ti semplifica la vita. 

Google Apps Script offre potenti ambienti di esecuzione che vanno da pulsanti interattivi e orientati all’utente a cron job completamente headless in background.

Metodo 1: attivazione tramite l’interfaccia del foglio

Se stai creando questo strumento per un team contabile non tecnico, probabilmente non vorranno aprire l’editor di codice di Apps Script solo per elaborare le fatture di oggi. 

Poiché abbiamo incluso la funzione onOpen() nel nostro codice, Apps Script collega automaticamente un menu personalizzato direttamente nell’interfaccia di Google Sheets ogni volta che il foglio di calcolo viene aperto.

1. Torna al tuo Foglio Google e aggiorna la pagina.
2. Attendi alcuni secondi e guarda la barra dei menu in alto. Vedrai un nuovo menu a discesa chiamato 🤖 AI Automations.
3. Fai clic e seleziona Fetch New Invoices.

4. La prima volta che lo esegui, Google ti chiederà di autorizzare lo script (per leggere la tua Gmail e inviare email per tuo conto). Una volta autorizzato, lo script si eseguirà in tempo reale. Potrai vedere i dati JSON estratti che popolano le righe sotto i tuoi occhi!

Metodo 2: automazione headless con trigger basati sul tempo

Se vuoi una vera automazione imposta e dimentica, puoi usare i trigger nativi Time-Driven per eseguire la pipeline in autonomia in background.

1. Nell’editor di Apps Script, fai clic su Trigger (icona dell’orologio) nella barra laterale sinistra.

2. Fai clic su Add Trigger nell’angolo in basso a destra.

3. Imposta la funzione su processInvoices.
4. Cambia l’origine dell’evento su Time-driven e impostalo per l’esecuzione con un timer orario (ad es. ogni 6 ore).
5. Fai clic su Salva.

La tua pipeline AI headless è ora completamente autonoma.

Anche con il computer completamente spento, i server di Google si “sveglieranno” ogni sei ore, eseguiranno la scansione della posta in arrivo, pareranno le fatture con Gemini, registreranno i dati in Sheets e torneranno in standby. 

Puoi monitorare l’esito di queste esecuzioni in background facendo clic sulla scheda Esecuzioni nell’editor di Apps Script per visualizzare i log.

Passaggio 4: testare l’estrazione dati con l’AI

Ora che il codice è pronto, dobbiamo testarlo per assicurarci che la pipeline di estrazione funzioni come previsto.

Vediamo due scenari pratici per capire come la Gemini API gestisce diversi formati di dati e come appaiono le risposte effettive.

Test 1: estrazione da email in testo semplice

Per prima cosa testeremo una fattura incorporata direttamente nel corpo dell’email.

1. Inviati un’email con oggetto "Invoice INV-2023-88493".
2. Nel corpo, scrivi un testo non strutturato come: "Ciao team, per favore paga Acme Corp $450.00 USD per la licenza software Q3."
3. Applica l’etichetta invoices all’email e assicurati che resti non letta.

4. Esegui lo script tramite il menu personalizzato.

Dietro le quinte, Gemini riceve questo testo non strutturato e rispetta rigorosamente il nostro schema JSON. 

Invece di rispondere con riempitivi conversazionali, restituisce un payload grezzo. 

Poiché la risposta è JSON perfettamente strutturato, il nostro array batchData.push() legge senza problemi extractedData.totalAmount e registra 6550 direttamente nel Foglio Google senza bisogno di complessa logica Regex.

Test 2: estrazione da un allegato PDF

Ora testiamo la vera potenza di Gemini 2.5 Flash passandogli un documento PDF.

1. Genera o scarica una fattura PDF di esempio (ad es. di $20.700,00 da ProTech Cloud Services).
2. Inviati via email il documento PDF. Puoi lasciare il corpo dell’email completamente vuoto!
3. Applica l’etichetta invoices e contrassegnala come non letta.

4. Esegui lo script. La pipeline rileverà l’allegato, lo convertirà in Base64 e Gemini leggerà visivamente il documento per estrarre il fornitore e l’importo totale.

È qui che l’architettura dimostra il suo valore. 

Non hai dovuto scrivere logica OCR (riconoscimento ottico dei caratteri) personalizzata, gestire una libreria separata per il parsing dei PDF o scrivere espressioni regolari per trovare l’importo totale. 

L’LLM ha gestito i dati visivi non strutturati in modo nativo.

Conclusione

Automatizzare i flussi di lavoro aziendali non richiede la gestione di infrastrutture pesanti o la lotta con loop di autorizzazione complessi. 

Abbinando Google Apps Script alla Gemini API, abbiamo costruito una pipeline di dati intelligente e serverless che gira interamente nel cloud che già usi ogni giorno.

La forza di questa architettura sta nella sua semplicità. Invece di fare il provisioning di server, configurare webhook o gestire file di credenziali sicuri su un server esterno, Apps Script gestisce nativamente contesto, autenticazione ed esecuzione. 

Nel frattempo, Gemini elimina la necessità di espressioni regolari fragili o software OCR costosi, trasformando corpi email disordinati e PDF non strutturati in righe di database prevedibili con una singola chiamata API.

Per approfondire le tue competenze ed esplorare cos’altro puoi costruire con l’accesso programmatico agli LLM, ti consiglio di dare un’occhiata a Introduction to APIs in Python di DataCamp o di immergerti nella progettazione di workflow intelligenti con il corso AI Agent Fundamentals .