> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Google-Cloud-Projekt erstellen">
    1. Rufen Sie die [Google Cloud Console](https://console.cloud.google.com/) auf
    2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus
    3. Notieren Sie sich die Projekt-ID
  </Step>

  <Step title="Erforderliche APIs aktivieren">
    1. Navigieren Sie zu **APIs & Services** > **Library**
    2. Suchen und aktivieren Sie die folgenden APIs:
       * **Google Sheets API**
       * **Google Drive API**
  </Step>

  <Step title="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**
  </Step>

  <Step title="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
  </Step>

  <Step title="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

    ```bash theme={null}
    # In .gitignore hinzufügen
    storage/app/google-service-account.json
    ```
  </Step>

  <Step title=".env-Datei konfigurieren">
    Fügen Sie Folgendes zu `.env` hinzu:

    ```env theme={null}
    GOOGLE_SERVICE_ENABLED=true
    GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
    ```
  </Step>

  <Step title="Scopes in config/google.php konfigurieren">
    ```php theme={null}
    'scopes' => [
        \Google\Service\Sheets::SPREADSHEETS,
        \Google\Service\Drive::DRIVE,
    ],
    ```
  </Step>

  <Step title="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. `your-service-account@your-project-id.iam.gserviceaccount.com`)
    5. Wählen Sie die Berechtigung aus:
       * **Betrachter** — Nur Lesezugriff
       * **Bearbeiter** — Lese- und Schreibzugriff
       * **Eigentümer** — Vollzugriff (nicht empfohlen)
  </Step>
</Steps>

## Verwendung

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

```php theme={null}
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**

```env theme={null}
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**

```php theme={null}
// 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:

```php theme={null}
// 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.


## Related topics

- [OAuth-2.0-Authentifizierung - Google Sheets API for Laravel](/de/packages/laravel-google-sheets/oauth.md)
- [Google Sheets API for Laravel](/de/packages/laravel-google-sheets/index.md)
- [Laravel Sanctum (API-Token-Authentifizierung)](/de/sanctum.md)
- [Laravel Socialite (Social Authentication)](/de/socialite.md)
- [LINE SDK für Laravel](/de/packages/laravel-line-sdk/index.md)