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

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

Google-Cloud-Projekt erstellen

Rufen Sie die Google Cloud Console auf
Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus
Notieren Sie sich die Projekt-ID

Erforderliche APIs aktivieren

Navigieren Sie zu APIs & Services > Library
Suchen und aktivieren Sie die folgenden APIs:
- Google Sheets API
- Google Drive API

Service Account erstellen

Navigieren Sie zu APIs & Services > Credentials
Klicken Sie auf Create Credentials > Service Account
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
Klicken Sie auf Create and Continue
Überspringen Sie beide optionalen Abschnitte und klicken Sie auf Done

Service-Account-Schlüssel generieren

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

JSON-Datei speichern

Verschieben Sie die heruntergeladene JSON-Datei nach storage/app/
Benennen Sie sie in google-service-account.json um
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

.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

Scopes in config/google.php konfigurieren

'scopes' => [
    \Google\Service\Sheets::SPREADSHEETS,
    \Google\Service\Drive::DRIVE,
],

Tabelle freigeben

Für jede Google-Sheets-Tabelle:

Öffnen Sie sie in Google Sheets
Klicken Sie auf die Schaltfläche Freigeben
Kopieren Sie das Feld client_email aus der JSON-Datei
Geben Sie sie für diese E-Mail-Adresse frei (z. B. [email protected])
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.

​Anwendungsfälle

​Voraussetzungen

​Einrichtung

​Verwendung

​Sicherheits-Best-Practices

​1. Service-Account-Berechtigungen einschränken

​2. Sichere Aufbewahrung der Schlüssel

​3. Bereitstellung in Produktionsumgebungen

​Referenz der Umgebungsvariablen

​Erweiterte Konfiguration

​JSON-String in Umgebungsvariablen speichern

​Fehlerbehebung

​Häufige Fehler

​Einrichtungstest