Service-Account-Authentifizierung - Google Sheets API für Laravel

Konfiguration der Service-Account-Authentifizierung für die Google Sheets API. Für die Server-zu-Server-Kommunikation.

Die Service-Account-Authentifizierung eignet sich hervorragend für den Zugriff auf Google Sheets zwischen Servern. Es sind keine Benutzerinteraktionen erforderlich; die Anwendung selbst bearbeitet die Tabellen. Sie eignet sich für Automatisierungsaufgaben und Hintergrundjobs.

​

Anwendungsfälle

• Server-zu-Server-Zugriff — Die Anwendung greift ohne Benutzerinteraktion auf Sheets zu
• Automatisierungssysteme — Hintergrundjobs, Cron-Aufgaben, automatische Berichte
• Feste Tabellen — Steuerung bestimmter Tabellen
• Produktionsumgebungen — Funktioniert zuverlässig ohne Zustimmungsablauf des Benutzers

​

Voraussetzungen

• Google-Cloud-Console-Projekt
• Aktivierung der Google Sheets API und Google Drive API
• Administratorrechte für das Projekt

​

Einrichtung

1. Google-Cloud-Projekt erstellen

   1. Rufen Sie die Google Cloud Console auf
   2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus
   3. Notieren Sie sich die Projekt-ID
2. Erforderliche APIs aktivieren

   1. Navigieren Sie zu APIs & Services > Library
   2. Suchen und aktivieren Sie die folgenden APIs:
      • Google Sheets API
      • Google Drive API
3. Service Account erstellen

   1. Navigieren Sie zu APIs & Services > Credentials
   2. Klicken Sie auf Create Credentials > Service Account
   3. Geben Sie die Service-Account-Details ein:
      • Service account name: Ein aussagekräftiger Name (z. B. „Laravel Sheets App”)
      • Service account ID: Wird automatisch generiert
      • Description: Optional
   4. Klicken Sie auf Create and Continue
   5. Überspringen Sie beide optionalen Abschnitte und klicken Sie auf Done
4. Service-Account-Schlüssel generieren

   1. Klicken Sie auf der Credentials-Seite auf den erstellten Service Account
   2. Wechseln Sie zur Registerkarte Keys
   3. Klicken Sie auf Add Key > Create new key
   4. Wählen Sie als Schlüsselformat JSON
   5. Klicken Sie auf Create
   6. Die JSON-Datei wird automatisch heruntergeladen
5. JSON-Datei speichern

   1. Verschieben Sie die heruntergeladene JSON-Datei nach storage/app/
   2. Benennen Sie sie in google-service-account.json um
   3. Wichtig: Fügen Sie sie zu .gitignore hinzu, um sie von der Versionskontrolle auszuschließen

   # In .gitignore hinzufügen
   storage/app/google-service-account.json
   
6. .env-Datei konfigurieren

   Fügen Sie Folgendes zu .env hinzu:

   GOOGLE_SERVICE_ENABLED=true
   GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
   
7. Scopes in config/google.php konfigurieren

   'scopes' => [
       \Google\Service\Sheets::SPREADSHEETS,
       \Google\Service\Drive::DRIVE,
   ],
   
8. Tabelle freigeben

   Für jede Google-Sheets-Tabelle:

   1. Öffnen Sie sie in Google Sheets
   2. Klicken Sie auf die Schaltfläche Freigeben
   3. Kopieren Sie das Feld client_email aus der JSON-Datei
   4. Geben Sie sie für diese E-Mail-Adresse frei (z. B. [e-mail])
   5. Wählen Sie die Berechtigung aus:
      • Betrachter — Nur Lesezugriff
      • Bearbeiter — Lese- und Schreibzugriff
      • Eigentümer — Vollzugriff (nicht empfohlen)

​

Verwendung

Nach Abschluss der Konfiguration wird der Service Account automatisch verwendet. Eine Konfiguration von Zugriffstokens ist nicht erforderlich.

use Revolution\Google\Sheets\Facades\Sheets;

// Der Service Account wird automatisch verwendet
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Referenz über den Tabellennamen (erfordert Zugriff auf die Drive API)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

​

Sicherheits-Best-Practices

​

1. Service-Account-Berechtigungen einschränken

• Geben Sie nur die notwendigen Tabellen frei
• Verwenden Sie Bearbeiter statt Eigentümer
• Überprüfen Sie die Zugriffsberechtigungen regelmäßig

​

2. Sichere Aufbewahrung der Schlüssel

• Nehmen Sie Service-Account-Schlüssel nicht in die Versionskontrolle auf
• Schließen Sie sie über .gitignore sicher aus
• Speichern Sie sie in Produktionsumgebungen an einem sicheren Ort außerhalb des Web-Roots
• Rotieren Sie die Schlüssel regelmäßig

​

3. Bereitstellung in Produktionsumgebungen

Zusätzliche Sicherheitsmaßnahmen:

• Speichern Sie den JSON-Schlüssel an einem sicheren Ort außerhalb des Web-Roots
• Verwenden Sie unterschiedliche Service Accounts pro Umgebung (Entwicklung, Staging, Produktion)
• Überwachen Sie die Nutzung dieser Konten in der Google Cloud Console
• Protokollieren Sie verdächtige Aktivitäten und richten Sie Warnmeldungen ein

​

Referenz der Umgebungsvariablen

Variable	Beschreibung	Beispiel
GOOGLE_SERVICE_ENABLED	Aktiviert die Service-Account-Authentifizierung	true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION	Pfad zur JSON-Datei	storage/app/google-service-account.json

​

Erweiterte Konfiguration

​

JSON-String in Umgebungsvariablen speichern

Anstatt die JSON-Datei als separate Datei zu speichern, können Sie den JSON-String als Umgebungsvariable speichern. Dies eignet sich für CI/CD-Umgebungen wie GitHub Actions.

Schritt 1: JSON-String in .env hinzufügen

GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", ...}'

Schritt 2: JSON-String in config/google.php dekodieren

// config/google.php
'service' => [
    'enable' => env('GOOGLE_SERVICE_ENABLED', false),
    'file' => json_decode(env('GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION', ''), true),
],

Auf diese Weise müssen Sie keine separate Datei speichern und können alles vollständig über die Umgebungsvariablen der CI/CD-Pipeline verwalten.

​

Fehlerbehebung

​

Häufige Fehler

Fehler „caller does not have permission”

• Prüfen Sie, ob die Tabelle für die E-Mail-Adresse des Service Accounts freigegeben ist
• Prüfen Sie bei Schreibvorgängen, ob die Berechtigung mindestens Bearbeiter ist

Fehler „File not found”

• Prüfen Sie, ob der Pfad zur JSON-Datei korrekt ist
• Prüfen Sie, ob die Datei existiert und der Webserver sie lesen kann

Fehler „API not enabled”

• Prüfen Sie, ob die Google Sheets API und Google Drive API in der Google Cloud Console aktiviert sind
• Warten Sie nach der Aktivierung der API einige Minuten

Fehler „Invalid credentials”

• Prüfen Sie, ob die JSON-Schlüsseldatei gültig und nicht beschädigt ist
• Prüfen Sie, ob der Service Account nicht gelöscht oder deaktiviert wurde
• Prüfen Sie, ob die Projekt-ID mit dem Google-Cloud-Projekt übereinstimmt

​

Einrichtungstest

Testroute zur Überprüfung der Service-Account-Einrichtung:

// routes/web.php
Route::get('/test-sheets', function () {
    try {
        $sheets = Sheets::spreadsheetList();
        return response()->json([
            'status' => 'success',
            'message' => 'Service-Account-Authentifizierung funktioniert',
            'spreadsheet_count' => count($sheets)
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'status' => 'error',
            'message' => $e->getMessage()
        ]);
    }
});

Rufen Sie diese Testroute auf, um zu prüfen, ob die Service-Account-Authentifizierung korrekt konfiguriert ist.