Google Sheets Integration

Lese und schreibe Google Sheets direkt aus deiner ChimerAI-App — ohne Python-Service, rein im Next.js-Layer via googleapis npm-Package.

Installation

chimerai add integration     # Landing Page + Shell
chimerai add google-sheets   # Google Sheets lib + API Route + Demo-Page

Generierte Dateien:

lib/google-sheets.ts                        ← Auth-Client, readSheet, appendRows, updateRange
app/api/integrations/sheets/route.ts        ← POST-Endpoint (read / append / update)
app/api/integrations/sheets/status/route.ts ← GET Health-Check (prüft ob Key vorhanden)
app/dashboard/integrations/sheets/page.tsx  ← Demo-UI

Google Cloud Setup

1. Projekt & API aktivieren

1. console.cloud.google.com öffnen
2. Projekt anlegen oder bestehendes wählen
3. APIs & Services → Bibliothek → „Google Sheets API" suchen → Aktivieren

2. Service Account erstellen

1. APIs & Services → Anmeldedaten → Anmeldedaten erstellen → Dienstkonto
2. Name: z.B. chimerai-sheets
3. Optionale Schritte (Zugriff / Nutzer) überspringen → Fertig

3. JSON-Key herunterladen

1. Auf der Seite „Anmeldedaten" das eben angelegte Dienstkonto anklicken
2. Tab Schlüssel → Schlüssel hinzufügen → Neuen Schlüssel erstellen → JSON
3. Die heruntergeladene .json-Datei sicher verwahren (enthält den Private Key)

4. Environment Variable setzen

Den gesamten Inhalt der JSON-Datei als einzeiligen String in .env eintragen:

# .env
GOOGLE_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"mein-projekt","private_key_id":"abc123","private_key":"-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n","client_email":"chimerai-sheets@mein-projekt.iam.gserviceaccount.com","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"..."}'

Hinweis zu Newlines: Der private_key-Wert enthält \n-Escape-Sequenzen. Diese bleiben in der .env-Datei als \n stehen — JSON.parse() wandelt sie beim Einlesen automatisch in echte Zeilenumbrüche um.

Sicherheit: Die Datei niemals ins Git-Repository committen. .gitignore enthält *.json und .env.

5. Google Sheet freigeben

Die Service Account hat eine eigene E-Mail-Adresse (sichtbar im JSON unter client_email). Das Ziel-Sheet muss für diese Adresse freigegeben werden:

1. Google Sheet öffnen → Teilen
2. client_email einfügen (z.B. chimerai-sheets@mein-projekt.iam.gserviceaccount.com)
3. Berechtigung wählen:
   • Betrachter → nur Lesen (readSheet)
   • Bearbeiter → Lesen + Schreiben (appendRows, updateRange)
4. „Personen benachrichtigen" deaktivieren (Service Accounts empfangen keine E-Mails)
5. Teilen

Öffentliche Sheets: Wenn das Sheet auf „Jeder mit Link kann anzeigen" steht, kann die Service Account es ebenfalls lesen — ohne explizite Freigabe. Für Schreibzugriff ist die direkte Freigabe aber trotzdem nötig.

Spreadsheet ID finden

Die ID steckt in der URL des Google Sheets:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                       Spreadsheet ID

API-Endpunkt

POST /api/integrations/sheets

Alle Operationen über einen einzigen Endpunkt, gesteuert via operation-Feld.

Lesen

POST /api/integrations/sheets
Content-Type: application/json

{
  "operation": "read",
  "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "range": "Sheet1!A1:D10"
}

Antwort:

{
  "rows": [
    ["Name", "Alter", "Stadt"],
    ["Anna", "30", "Wien"],
    ["Max", "25", "Berlin"]
  ]
}

Zeilen anhängen

POST /api/integrations/sheets
Content-Type: application/json

{
  "operation": "append",
  "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "range": "Sheet1",
  "values": [
    ["Eva", "28", "Zürich"]
  ]
}

Bereich aktualisieren

POST /api/integrations/sheets
Content-Type: application/json

{
  "operation": "update",
  "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
  "range": "Sheet1!A2:C2",
  "values": [
    ["Anna", "31", "Graz"]
  ]
}

GET /api/integrations/sheets/status

Prüft ob GOOGLE_SERVICE_ACCOUNT_KEY konfiguriert ist:

{ "ok": true }
// oder
{ "ok": false, "error": "GOOGLE_SERVICE_ACCOUNT_KEY is not configured" }

Range-Notation (A1-Notation)

Sheet-Namen sind case-sensitive. Bei Leerzeichen im Sheet-Namen mit einfachen Anführungszeichen quoten: 'Mein Sheet'!A1:B10

Lib-Funktionen direkt nutzen

import { readSheet, appendRows, updateRange } from '@/lib/google-sheets';

// Lesen
const rows = await readSheet('SPREADSHEET_ID', 'Sheet1!A1:C10');
// rows: string[][]

// Anhängen
await appendRows('SPREADSHEET_ID', 'Sheet1', [
  ['Neuer Eintrag', '2026-06-17', 'Wien'],
]);

// Aktualisieren
await updateRange('SPREADSHEET_ID', 'Sheet1!B2', [['Neuer Wert']]);

Sicherheit

• GOOGLE_SERVICE_ACCOUNT_KEY niemals in Git committen
• Nur die Google Sheets API aktivieren — kein Drive, Gmail, o.ä.
• Wo möglich nur Betrachter-Zugriff vergeben (kein Schreibrecht wenn nicht benötigt)
• Keys regelmäßig rotieren: Google Cloud Console → Dienstkonto → Schlüssel → alten löschen, neuen erstellen

Troubleshooting

Rate Limits (Google Sheets API)

Bei höherem Volumen: Request-Batching oder Caching-Layer einbauen.