Google Apps Script und die Gemini API Tutorial: Intelligente Datenextraktion

Manuelle Dateneingabe ist der Produktivitätskiller schlechthin. Wenn dein Team Daten aus operativen E-Mails wie Rechnungen, Buchungsbestätigungen oder Kundenfeedback-Formularen extrahiert, kennst du vermutlich den Albtraum klassischer Parsing-Methoden.

Früher setzten Entwicklerinnen und Entwickler auf Regular Expressions (Regex), um Details wie Rechnungsnummern oder Beträge zu ziehen. Doch Regex ist extrem fragil: Ändert ein Anbieter sein E-Mail-Template oder rutscht ein Zeilenumbruch an die falsche Stelle, bricht der Parser unbemerkt zusammen.

In diesem Tutorial zeige ich dir, wie du mit Generativer KI eine vollständig automatisierte, headless Pipeline baust, die dieses Problem löst. Wir schreiben ein schlankes Skript, das ungelesene Gmail-Nachrichten ausliest, den unstrukturierten Text an die Gemini API zur intelligenten Extraktion übergibt und die perfekt strukturieren JSON-Daten direkt in ein Google Sheet schreibt.

Voraussetzungen:

• Ein Google-Konto
• Grundkenntnisse in JavaScript (Google Apps Script)
• Ein Gemini API-Schlüssel

Was ist Google Apps Script?

Google Apps Script ist eine cloudbasierte, schnelle Entwicklungsplattform auf Basis von JavaScript, mit der du Google Workspace-Apps wie Google Docs, Sheets, Slides und mehr automatisieren, anpassen und erweitern kannst.

Da die Plattform direkt auf den Servern von Google läuft, musst du keine Software installieren, keine lokale Umgebung einrichten und keine Infrastruktur managen.

Apps Script gibt Entwicklerinnen, Entwicklern und Low-Code-Buildern die Möglichkeit, programmgesteuert mit Google Workspace-Tools wie Docs, Sheets, Slides und Drive zu interagieren. Du kannst Automatisierungen über eigene Menüs, Button-Klicks oder zeitgesteuerte Abläufe ausführen oder Add-ons für den Google Workspace Marketplace entwickeln und veröffentlichen.

Wie Google Apps Script funktioniert

Google Apps Script nimmt dir das schwere Backend-Heben bei Konfiguration und API-Authentifizierung ab, sodass du dich auf Logik und Daten konzentrieren kannst. Das gelingt durch mehrere Features:

• Cloud-nativer Editor: Du schreibst, debuggst und deployest deinen JavaScript-Code komplett in einer webbasierten IDE direkt im Browser.
• Integrierte Services: Statt dich mit OAuth und komplexen API-Calls herumzuschlagen, nutzt du vorgefertigte globale Objekte (wie SpreadsheetApp, MailApp oder DriveApp), um nativ mit Google-Services zu arbeiten.
• Ereignisgesteuerte Trigger: Skripte lassen sich manuell über benutzerdefinierte Menüs ausführen oder automatisch über zeitgesteuerte Trigger (z. B. täglich um Mitternacht) und ereignisgesteuerte Trigger (z. B. bei einer Formularübermittlung in Google Forms).

Die Google Apps Script-Architektur: Gmail-zu-Sheets-Pipeline

Bevor wir den Code schreiben, skizzieren wir den Datenfluss in dieser Pipeline. Die Architektur basiert auf vier Komponenten, die zusammenarbeiten:

• Gmail (Quelle): Der Prozess startet mit einer Suche im Posteingang per Standardoperatoren (z. B. is:unread label:invoices). Das Skript isoliert die richtigen Threads und extrahiert sowohl den Nur-Text-Body als auch angehängte PDF-Dateien.
• Apps Script (Compute): Dient als Orchestrierungsschicht. Es iteriert durch ungelesene Threads, konvertiert Anhänge in Base64-Daten und übernimmt das Fehler- und Batch-Handling.
• Gemini API (Transformations-Engine): Apps Script sendet ein multimodales Payload (E-Mail-Text plus PDFs) an das Modell Gemini 2.5 Flash. Durch ein strenges JSON-Antwortschema in der API-Anfrage zwingen wir das Modell, exakte Werte wie Anbieter, Gesamtbetrag und Währung auszulesen, statt Konversationstext zu generieren.
• Google Sheets (Ziel): Sobald Gemini das strukturierte JSON zurückgibt, parst Apps Script die Ergebnisse, bündelt sie in einem Array und schreibt die Daten per setValues() gesammelt in die nächste freie Zeile deiner aktiven Tabelle.

Warum Google Apps Script als Compute-Schicht für diesen Build?

Der größte Vorteil ist: keinerlei Infrastruktur-Overhead. Du musst keine Server bereitstellen, keine Docker-Container konfigurieren und keine komplizierten OAuth-Flows aufsetzen, nur um E-Mails zu lesen oder in ein Spreadsheet zu schreiben.

Weil Apps Script sich nativ mit Services wie GmailApp und SpreadsheetApp integriert, übernimmt Google die Authentifizierung intern. Du schreibst einfach den Code und verbindest die Endpunkte.

Schritt 1: Richte deine Google Apps Script-Umgebung ein

Bevor wir Code schreiben, kümmern wir uns um die externen Abhängigkeiten. Dazu gehören der Zugriff auf die Gemini API, das Anlegen unseres Ziel-Spreadsheets und das Konfigurieren des Gmail-Posteingangs, um eingehende Rechnungen korrekt zu taggen.

Den Gemini API-Schlüssel erzeugen

Für die intelligente Datenextraktion brauchen wir Zugriff auf die Gemini API.

1. Navigiere zu Google AI Studio und melde dich mit deinem Google-Konto an.
2. Klicke im linken Navigationsmenü auf Get API key.
3. Klicke auf Create API key. Du kannst den Schlüssel in einem vorhandenen Google Cloud-Projekt anlegen oder AI Studio ein neues erstellen lassen.
4. Kopiere den generierten String.

Sicherheits-Best Practice: Verliere diesen Schlüssel nicht, aber vor allem: Hinterlege ihn nicht im Klartext im Code. Behalte ihn in der Zwischenablage oder in einem sicheren Notiztool; im nächsten Schritt sichern wir ihn in der Apps Script-Umgebung.

Google Sheet vorbereiten und den Schlüssel sichern

Wir brauchen einen Ort, um die extrahierten Daten zu speichern. Dieses Sheet dient auch als Startrampe für unser Automatisierungsskript.

1. Datenbank-Header anlegen Erstelle ein neues leeres Google Sheet. Lege in der ersten Zeile folgende Spalten an, passend zum JSON-Schema, das wir im Skript definieren werden:

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

Fixiere die Kopfzeile, damit sie beim Wachsen der Daten sichtbar bleibt.

2. Apps Script öffnen und den API-Schlüssel speichern Jetzt öffnen wir den Apps Script-Editor direkt aus dem Sheet. So wird der Code automatisch mit genau dieser Tabelle verknüpft.

1. Klicke in deinem Google Sheet im oberen Menü auf Erweiterungen > Apps Script.
2. Sobald der Editor geöffnet ist, klicke in der linken Seitenleiste auf das Zahnrad für Projekteinstellungen.

3. Scrolle nach unten bis zum Abschnitt Skripteigenschaften.
4. Klicke auf Skripteigenschaft hinzufügen.
5. Gib unter Property exakt GEMINI_API_KEY ein.
6. Füge unter Value den zuvor kopierten API-Schlüssel aus AI Studio ein.
7. Klicke auf Skripteigenschaften speichern.

Der Code liest diesen Wert später zur Laufzeit sicher aus, ohne deine Zugangsdaten offenzulegen.

Schritt 2: Schreibe den Google Apps Script-Code

Lösche im Apps Script-Editor zunächst jeglichen Standardcode. Wir bauen unsere Automatisierungs-Engine Block für Block auf.

1. Konfiguration und UI-Setup

Wir starten mit einem globalen Konfigurationsobjekt. Das ist eine Clean-Code-Best Practice: Alle fixen Variablen liegen an einem Ort, sodass du später nur diesen Block anpassen musst.

Außerdem fügen wir eine onOpen()-Funktion hinzu. Dieser eingebaute Apps Script-Trigger erzeugt automatisch ein benutzerdefiniertes Menü in deinem Google Sheet, damit auch Nicht-Techies das Skript manuell starten können, ohne den Code-Editor zu öffnen.

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. Die Orchestrierung einrichten

Die Funktion processInvoices() ist der Hauptorchestrator. Sie beginnt damit, deinen API-Schlüssel sicher aus den zuvor hinterlegten Skripteigenschaften zu laden.

Dann nutzt sie den integrierten GmailApp-Service, um den Posteingang zu durchsuchen.

Mit GmailApp.search(CONFIG.searchQuery) holt das Skript ein Array an Threads, die unserer Regel is:unread label:invoices entsprechen.

Falls Treffer vorhanden sind, iteriert es durch jeden Thread, greift sich die neueste Nachricht, extrahiert den Nur-Text-Body und isoliert angehängte PDFs.

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. E-Mails und multimodale PDFs verarbeiten

Während wir durch die E-Mail-Threads loopen, holen wir die neueste Nachricht. Rechnungen kommen jedoch selten als reiner Text, sondern fast immer als PDF-Anhang.

Dank Gemini 2.5 Flash, das nativ multimodal ist, durchläuft unser Skript latestMessage.getAttachments(), sammelt PDFs, konvertiert sie in Base64 und übergibt sie als inlineData direkt im API-Payload.

Gemini „liest“ das PDF visuell und extrahiert die Daten genauso mühelos wie Text.

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. Batch-Einfügen und Fehlerbehandlung

Zur Performance-Optimierung schreiben wir nicht Zeile für Zeile ins Spreadsheet.

Stattdessen schieben wir die extrahierten JSON-Daten in ein Array (batchData) und schreiben sie am Ende gesammelt per setValues() hinein.

Beachte den try...catch-Block.

Falls Gemini halluziniert oder bei einer E-Mail scheitert, stürzt das Skript nicht ab. Es fängt den Fehler ab und nutzt MailApp.sendEmail(), um die Administratorin bzw. den Administrator sofort zu informieren. So bleibt die Pipeline gut überwachbar.

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

Zum Schluss ruft das Skript für jede verarbeitete E-Mail thread.markRead() auf. So stellt es sicher, dass beim nächsten Lauf nur neue E-Mails berücksichtigt werden.

5. Die Gemini API-Hilfsfunktion (JSON-Modus)

Beim Aufruf von LLMs wird oft mit Prompts wie „Gib ein JSON zurück“ gearbeitet. Modelle antworten jedoch häufig mit Floskeln (z. B. „Klar, hier sind die Daten: [JSON]“), was nachgelagerte Parser aus dem Tritt bringt.

Mit responseMimeType: "application/json" und einem strikten responseSchema erzwingen wir, dass die Gemini REST API ausschließlich ein garantiertes JSON-Objekt mit genau unseren Spaltenköpfen zurückliefert.

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

Schritt 3: Automatisiere deine Google Apps Script-Pipeline

Code ist nur dann wertvoll, wenn er dir das Leben leichter macht.

Google Apps Script bietet mächtige Ausführungsoptionen – von interaktiven Buttons bis hin zu komplett headless Cron-Jobs im Hintergrund.

Methode 1: Auslösung über die Spreadsheet-Oberfläche

Wenn du dieses Tool für ein nicht-technisches Buchhaltungsteam baust, wird es den Apps Script-Editor nicht öffnen wollen, nur um die heutigen Rechnungen zu verarbeiten.

Weil wir die Funktion onOpen() eingebaut haben, bindet Apps Script bei jedem Öffnen der Tabelle automatisch ein eigenes Menü in die Google Sheets-Oberfläche ein.

1. Gehe zurück zu deinem Google Sheet und lade die Seite neu.
2. Warte ein paar Sekunden und schau in die Menüleiste. Du siehst ein neues Dropdown namens 🤖 AI Automations.
3. Klicke darauf und wähle Fetch New Invoices.

4. Beim ersten Ausführen fordert dich Google zur Autorisierung auf (um dein Gmail zu lesen und E-Mails in deinem Namen zu senden). Nach der Freigabe läuft das Skript in Echtzeit. Du kannst zusehen, wie die extrahierten JSON-Daten Zeile für Zeile im Sheet auftauchen.

Methode 2: Headless-Automatisierung per zeitgesteuertem Trigger

Wenn du echte Einrichten und vergessen-Automatisierung willst, nutze Time-driven Trigger, um die Pipeline autonom im Hintergrund laufen zu lassen.

1. Klicke im Apps Script-Editor in der linken Seitenleiste auf Trigger (Uhr-Icon).

2. Klicke unten rechts auf Trigger hinzufügen.

3. Wähle als Funktion processInvoices aus.
4. Stelle die Ereignisquelle auf Zeitgesteuert und wähle einen Stundentimer (z. B. alle 6 Stunden).
5. Klicke auf Speichern.

Deine headless KI-Pipeline läuft jetzt völlig autonom.

Selbst wenn dein Computer aus ist, wachen die Google-Server alle sechs Stunden auf, scannen deinen Posteingang, parsen die Rechnungen mit Gemini, schreiben die Daten in Sheets und gehen wieder schlafen.

Du kannst Erfolg oder Fehler dieser Hintergrundläufe im Tab „Ausführungen“ im Apps Script-Editor überwachen.

Schritt 4: Die KI-Datenextraktion testen

Jetzt, da der Code steht, testen wir, ob die Extraktions-Pipeline wie erwartet funktioniert.

Wir betrachten zwei praxisnahe Szenarien, um zu sehen, wie die Gemini API unterschiedliche Datenformate behandelt und wie die Antworten aussehen.

Test 1: Extraktion aus einer Nur-Text-E-Mail

Zuerst testen wir eine Rechnung, die direkt im E-Mail-Body steht.

1. Sende dir selbst eine E-Mail mit dem Betreff „Invoice INV-2023-88493“.
2. Schreibe in den Body unstrukturierten Text, z. B.: „Hi Team, bitte zahlt Acme Corp $450.00 USD für die Q3-Softwarelizenz.“
3. Vergib das Label invoices für die E-Mail und lasse sie ungelesen.

4. Führe das Skript über das benutzerdefinierte Menü aus.

Im Hintergrund erhält Gemini diesen unstrukturierten Text und hält sich strikt an unser JSON-Schema.

Statt mit Floskel-Text zu antworten, kommt eine rohe Nutzlast zurück.

Weil die Antwort perfekt strukturiertes JSON ist, kann unser batchData.push()-Array nahtlos extractedData.totalAmount lesen und 6550 direkt in Google Sheets schreiben – ganz ohne komplexe Regex-Logik.

Test 2: Extraktion aus einem PDF-Anhang

Als Nächstes testen wir die wahre Stärke von Gemini 2.5 Flash mit einem PDF-Dokument.

1. Erstelle oder lade eine Beispielrechnung als PDF (z. B. über $20.700,00 von ProTech Cloud Services).
2. Schicke dir das PDF per E-Mail. Den E-Mail-Body kannst du leer lassen!
3. Vergib das Label invoices und markiere die E-Mail als ungelesen.

4. Führe das Skript aus. Die Pipeline erkennt den Anhang, konvertiert ihn in Base64 und Gemini liest das Dokument visuell, um Anbieter und Gesamtbetrag zu extrahieren.

Hier zeigt die Architektur ihren Wert.

Du musstest keine eigene OCR (Optical Character Recognition) schreiben, keine separate PDF-PARSING-Bibliothek einbinden und keine Regex bauen, um den Gesamtbetrag zu finden.

Das LLM hat unstrukturierte visuelle Daten nativ verarbeitet.

Fazit

Business-Workflows zu automatisieren, erfordert keine schwere Infrastruktur und keine Kämpfe mit komplexen Autorisierungs-Workflows.

Mit Google Apps Script und der Gemini API haben wir eine intelligente, serverlose Datenpipeline gebaut, die vollständig in der Cloud-Umgebung läuft, die du ohnehin täglich nutzt.

Die Stärke dieser Architektur liegt in ihrer Einfachheit. Statt Server bereitzustellen, Webhooks zu konfigurieren oder sensible Zugangsdaten extern zu verwalten, übernimmt Apps Script Kontext, Authentifizierung und Ausführung nativ.

Gleichzeitig macht Gemini brüchige Regulärausdrücke oder teure OCR-Software überflüssig und verwandelt chaotische E-Mail-Bodys und unstrukturierte PDFs mit einem einzigen API-Call in verlässliche Datenbankzeilen.

Wenn du deine Kompetenzen weiter ausbauen und mehr dazu lernen willst, was sich mit programmgesteuertem Zugriff auf LLMs bauen lässt, empfehle ich dir DataCamps Introduction to APIs in Python oder einen Deep Dive in intelligente Workflows mit dem AI Agent Fundamentals Kurs.