Tutorial Google Apps Script și API-ul Gemini: extragere inteligentă de date

Introducerea manuală de date este inamicul productivității. Dacă echipa ta se bazează pe extragerea datelor din emailuri operaționale, precum facturi, confirmări de rezervare sau formulare de feedback de la clienți, probabil cunoști bine coșmarul metodelor tradiționale de parsare. 

Istoric, dezvoltatorii s-au bazat pe expresii regulate (Regex) pentru a extrage detalii precum numerele de factură sau sumele de plată. Dar Regex este extrem de fragil; în momentul în care un furnizor își schimbă șablonul de email sau adaugă un rând nou aleatoriu, întregul parser se rupe în tăcere.

În acest tutorial, îți voi arăta cum să construiești un pipeline complet automatizat, fără interfață, care rezolvă această problemă folosind AI generativ. Vom scrie un script ușor care citește mesajele necitite din Gmail, trimite textul nestructurat către API-ul Gemini pentru extragere inteligentă și înregistrează datele JSON perfect structurate direct într-un Google Sheet.

Condiții prealabile:

• Un cont Google
• Familiarizare de bază cu JavaScript (Google Apps Script)
• O cheie de API Gemini

Ce este Google Apps Script?

Google Apps Script este o platformă de dezvoltare rapidă, bazată pe JavaScript, în cloud, care îți permite să automatizezi, personalizezi și extinzi aplicațiile Google Workspace precum Google Docs, Sheets, Slides și altele. 

Deoarece platforma rulează direct pe serverele Google, nu este nevoie să instalezi software, să configurezi medii locale sau să gestionezi infrastructură. 

Apps Script le oferă dezvoltatorilor/creatorilor low-code posibilitatea de a interacționa programatic cu instrumente Google Workspace precum Docs, Sheets, Slides, Drive și altele. Poți construi și rula automatizări prin meniuri personalizate, clicuri pe butoane sau programări bazate pe timp, ori poți folosi serviciul pentru a construi și publica add-on-uri în Google Workspace Marketplace.

Cum funcționează Google Apps Script

Google Apps Script elimină efortul greu al configurării backend-ului și autentificării API, permițându-ți să te concentrezi direct pe logică și date. Face asta prin mai multe funcționalități:

• Editor nativ în cloud: Îți scrii, debugezi și publici codul JavaScript integral într-un IDE web integrat în browser.
• Servicii integrate: În loc să te lupți cu OAuth și apeluri API complexe, folosești obiecte globale gata de utilizare (precum SpreadsheetApp, MailApp sau DriveApp) pentru a interacționa nativ cu serviciile Google.
• Trigger-e bazate pe evenimente: Scripturile pot fi executate manual prin butoane din meniuri personalizate sau pot fi programate să ruleze automat folosind trigger-e bazate pe timp (de ex., la miezul nopții) și trigger-e bazate pe evenimente (de ex., când un utilizator trimite un formular Google).

Arhitectura Google Apps Script: pipeline Gmail către Sheets

Înainte să scriem scriptul, haide să cartografiem cum se mișcă datele prin acest pipeline. Arhitectura se bazează pe patru componente distincte care lucrează împreună:

• Gmail (Sursă): Procesul începe prin interogarea inbox-ului folosind operatori standard de căutare (precum is:unread label:invoices). Scriptul izolează conversațiile corecte și extrage atât corpul text simplu, cât și orice fișiere PDF atașate.
• Apps Script (Compute): Acționează ca un strat de orchestrare. Parcurge conversațiile necitite, formatează atașamentele în date base64 și gestionează logica pentru raportarea erorilor și procesarea în loturi.
• API-ul Gemini (Motor de transformare): Apps Script trimite un payload multimodal (textul emailului plus PDF-urile) către modelul Gemini 2.5 Flash. Prin transmiterea unei scheme stricte de răspuns JSON în apelul API, forțăm modelul să extragă valori exacte precum furnizor, sumă totală și monedă, în loc să genereze text conversațional.
• Google Sheets (Destinație): După ce Gemini returnează JSON-ul structurat, Apps Script parsează rezultatele, le grupează într-un singur array și inserează în lot datele în următorul rând liber al foii de calcul active folosind setValues().

De ce să folosești Google Apps Script ca strat de compute pentru acest build? 

Principalul beneficiu este eliminarea completă a poverii de infrastructură. Nu e nevoie de provizionarea niciunui server și nu trebuie să configurezi containere Docker sau fluxuri OAuth complicate doar ca să îți citești emailurile sau să scrii într-un spreadsheet. 

Pentru că Apps Script se integrează nativ cu servicii precum GmailApp și SpreadsheetApp, Google gestionează autentificarea intern. Tu doar scrii codul și conectezi endpoint-urile.

Pasul 1: Pregătește-ți mediul Google Apps Script

Înainte să scriem orice cod, trebuie să pregătim dependențele externe. Asta implică asigurarea accesului la API-ul Gemini, crearea foii noastre de calcul destinație și configurarea inbox-ului Gmail pentru a eticheta corect facturile primite.

Generarea cheii de API Gemini

Pentru a alimenta extragerea inteligentă a datelor, avem nevoie de acces la API-ul Gemini.

1. Navighează la Google AI Studio și autentifică-te cu contul tău Google.
2. În meniul de navigare din stânga, dă clic pe Get API key.
3. Apasă butonul Create API key. Poți alege să creezi această cheie într-un proiect Google Cloud existent sau să lași AI Studio să creeze unul nou pentru tine.
4. Copiază șirul generat. 

Bune practici de securitate: Nu pierde această cheie, dar mai important, nu plănui s-o salvezi hardcodată în clar în cod. Păstreaz-o în clipboard sau într-un notițar securizat pentru moment; în pasul următor o vom bloca în siguranță în mediul Apps Script.

Pregătirea Google Sheet și securizarea cheii

Avem nevoie de un loc în care să stocăm datele extrase. Această foaie va acționa și ca punct de lansare pentru scriptul nostru de automatizare.

1. Configurează headerele bazei de date Creează un nou Google Sheet gol. Pe primul rând, creează următoarele headere de coloană pentru a corespunde schemei JSON pe care o vom defini în script:

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

Îngheață rândul de sus ca headerele să rămână vizibile pe măsură ce cresc datele.

2. Accesează Apps Script și stochează cheia API Acum că foaia există, putem deschide editorul Apps Script direct din ea. Asta leagă automat codul de acest spreadsheet specific.

1. În Google Sheet, dă clic pe Extensions > Apps Script din meniul de sus.
2. După ce se deschide editorul, uită-te în bara laterală din stânga și apasă pe pictograma de setări pentru a deschide Project Settings.

3. Derulează până jos pentru a găsi secțiunea Script Properties.
4. Apasă Add script property.
5. La Property, tastează exact GEMINI_API_KEY.
6. La Value, lipește cheia API copiată mai devreme din AI Studio.
7. Apasă Save script properties.

Codul pe care îl vom scrie mai târziu va prelua acum în siguranță această valoare la runtime fără a-ți expune credențialele.

Pasul 2: Scrie codul Google Apps Script

Cât timp ești în editorul Apps Script, șterge orice cod implicit. Vom construi motorul de automatizare bloc cu bloc.

1. Configurație și configurare UI

Începem prin definirea unui obiect global de configurare. Este o bună practică de clean code care grupează toate variabilele hardcodate într-un singur loc, astfel încât va trebui să editezi doar acest bloc de sus.

Adăugăm și o funcție onOpen(). Acest trigger încorporat în Apps Script creează automat un meniu personalizat în Google Sheet, permițând utilizatorilor non-tehnici să ruleze scriptul manual fără să deschidă editorul de cod.

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. Configurarea orchestrării

Funcția processInvoices() acționează ca orchestrator principal. Începe prin a prelua în siguranță cheia ta API din Script Properties configurate mai devreme. 

Apoi, folosește serviciul încorporat GmailApp pentru a-ți interoga inbox-ul.

Apelând GmailApp.search(CONFIG.searchQuery), scriptul obține un array de conversații de email care corespund regulii noastre is:unread label:invoices. 

Dacă găsește potriviri, iterează prin fiecare conversație, preia cel mai recent mesaj, extrage corpul text simplu și izolează orice fișier PDF atașat.

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. Procesarea emailurilor și a PDF-urilor multimodale

Pe măsură ce parcurgem conversațiile de email, preluăm cel mai recent mesaj. Totuși, rareori facturile sosesc ca text simplu; aproape întotdeauna sunt atașate ca PDF-uri. 

Folosind Gemini 2.5 Flash, care este nativ multimodal, scriptul nostru parcurge latestMessage.getAttachments(), preia orice PDF-uri, le convertește într-un șir Base64 și le transmite direct către payload-ul API ca inlineData. 

Gemini „citește” PDF-ul vizual și extrage datele la fel de ușor cum citește textul.

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. Inserare în lot și gestionarea erorilor

Pentru a optimiza performanța, nu scriem în spreadsheet rând cu rând. 

În schimb, împingem datele JSON extrase într-un array (batchData) și le scriem pe toate odată la final folosind setValues().

Observă blocul try...catch. 

Dacă Gemini halucinează sau eșuează pe un email anume, scriptul nu se blochează complet. În schimb, prinde grațios eroarea și folosește MailApp.sendEmail() pentru a alerta imediat administratorul, asigurând o bună observabilitate.

 // 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());
}

În final, scriptul apelează thread.markRead() pentru fiecare email procesat. Asta asigură că, la următoarea rulare, scriptul ignoră complet aceste emailuri și caută doar altele noi.

5. Funcția helper pentru API-ul Gemini (mod JSON)

Când apelează LLM-uri, dezvoltatorii folosesc adesea tehnici de Prompt Engineering precum „Return a JSON block”. Totuși, modelele răspund frecvent cu umplutură conversațională (de ex. „Sigur, iată datele tale: [JSON]”), ceea ce face ca parser-ele din aval să se blocheze.

Setând responseMimeType: "application/json" și furnizând o responseSchema strictă, forțăm API-ul REST Gemini să răspundă doar cu un obiect JSON garantat care conține exact headerele noastre de coloană din spreadsheet.

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);
}

Pasul 3: Automatizează pipeline-ul tău Google Apps Script

Codul este valoros doar dacă îți face viața mai ușoară. 

Google Apps Script oferă medii puternice de execuție, de la butoane interactive, orientate către utilizator, la joburi cron complet fără interfață, în fundal.

Metoda 1: Declanșare din interfața spreadsheet-ului

Dacă construiești acest instrument pentru o echipă de contabilitate non-tehnică, probabil nu vor să deschidă editorul de cod Apps Script doar ca să proceseze facturile de azi. 

Deoarece am inclus funcția onOpen() în cod, Apps Script leagă automat un meniu personalizat direct în interfața Google Sheets de fiecare dată când foaia de calcul este deschisă.

1. Întoarce-te la Google Sheet și reîmprospătează pagina.
2. Așteaptă câteva secunde și uită-te în bara de meniu de sus. Vei vedea un nou dropdown numit 🤖 AI Automations.
3. Dă clic pe el și selectează Fetch New Invoices.

4. La prima rulare, Google îți va cere să autorizezi scriptul (pentru a-ți citi Gmail și a trimite emailuri în numele tău). Odată autorizat, scriptul se va executa în timp real. Poți urmări cum datele JSON extrase se umplu în rânduri chiar sub ochii tăi!

Metoda 2: Automatizare fără interfață prin trigger-e bazate pe timp

Dacă vrei o automatizare adevărată de tip set it and forget it, poți folosi trigger-ele native Time-Driven pentru a rula pipeline-ul autonom, în fundal.

1. În editorul Apps Script, dă clic pe Triggers (pictograma ceas) din bara laterală stângă.

2. Apasă Add Trigger în colțul din dreapta jos.

3. Setează funcția la processInvoices.
4. Schimbă sursa evenimentului la Time-driven și setează-l să ruleze pe un timer de oră (de ex., la fiecare 6 ore).
5. Apasă Save.

Pipeline-ul tău AI fără interfață este acum complet autonom.

Chiar dacă îți oprești complet computerul, serverele Google se vor „trezi” la fiecare șase ore, îți vor scana inbox-ul, vor parsa facturile prin Gemini, vor înregistra datele în Sheets și vor reveni în stand-by. 

Poți monitoriza succesul sau eșecul acestor execuții din fundal accesând fila Executions în editorul Apps Script pentru a vedea logurile.

Pasul 4: Testarea extragerii de date cu AI

Acum că avem codul la locul lui, trebuie să-l testăm pentru a ne asigura că pipeline-ul de extragere funcționează conform așteptărilor.

Hai să analizăm două scenarii practice pentru a vedea cum API-ul Gemini gestionează formate diferite de date și cum arată răspunsurile reale.

Test 1: Extragere din email text simplu

Mai întâi, vom testa o factură încorporată direct în corpul emailului.

1. Trimite-ți un email cu subiectul „Invoice INV-2023-88493”.
2. În corp, scrie un text nestructurat de tipul: „Salut echipă, vă rog să plătiți Acme Corp 450,00 $ USD pentru licența software Q3.”
3. Aplică eticheta invoices emailului și asigură-te că rămâne necitit.

4. Rulează scriptul prin meniul personalizat.

În culise, Gemini primește acest text nestructurat și aderă strict la schema noastră JSON. 

În loc să răspundă cu umplutură conversațională, returnează un payload brut. 

Pentru că răspunsul este JSON perfect structurat, array-ul nostru batchData.push() citește fără probleme extractedData.totalAmount și înregistrează 6550 direct în Google Sheet fără a necesita logică Regex complexă.

Test 2: Extragere dintr-un atașament PDF

În continuare, să testăm adevărata putere a Gemini 2.5 Flash trimițându-i un document PDF.

1. Generează sau descarcă un exemplu de factură PDF (de ex., pentru 20.700,00 $ de la ProTech Cloud Services).
2. Trimite-ți ție însuți documentul PDF. Poți lăsa corpul emailului complet gol!
3. Aplică eticheta invoices și marchează-l ca necitit.

4. Rulează scriptul. Pipeline-ul va detecta atașamentul, îl va converti în Base64, iar Gemini va citi vizual documentul pentru a extrage furnizorul și suma totală.

Aici se dovedește valoarea arhitecturii. 

Nu a trebuit să scrii logică OCR (Optical Character Recognition) personalizată, să gestionezi o bibliotecă separată de parsare PDF sau să scrii expresii regulate pentru a găsi suma totală. 

LLM-ul a gestionat nativ datele vizuale nestructurate.

Concluzie

Automatizarea fluxurilor de lucru de business nu necesită gestionarea unei infrastructuri grele sau lupta cu bucle de autorizare complexe. 

Combinând Google Apps Script cu API-ul Gemini, am construit un pipeline inteligent, serverless, care rulează integral în ecosistemul cloud pe care îl folosești deja zilnic.

Punctul forte al acestei arhitecturi constă în simplitate. În loc să provizionezi servere, să configurezi webhook-uri sau să gestionezi fișiere de credențiale securizate pe un server extern, Apps Script gestionează nativ contextul, autentificarea și execuția. 

Între timp, Gemini elimină nevoia pentru expresii regulate fragile sau software OCR costisitor, transformând corpuri de email dezordonate și PDF-uri nestructurate în rânduri de date previzibile cu un singur apel API.

Ca să-ți duci abilitățile mai departe și să explorezi ce altceva poți construi cu acces programatic la LLM-uri, îți recomand să consulți Introduction to APIs in Python de la DataCamp sau să aprofundezi proiectarea fluxurilor inteligente cu AI Agent Fundamentals course.