Autenticazione Service Account - Google Sheets API for Laravel

Configura l’autenticazione Service Account per Google Sheets API. Ideale per la comunicazione server-to-server.

L’autenticazione Service Account è ideale quando accedi a Google Sheets tra server. Non è richiesta alcuna interazione dell’utente e l’applicazione stessa opera sui fogli di calcolo. È adatta ad attività automatizzate e job in background.

​

Casi d’uso

• Accesso server-to-server — l’app accede a Sheets senza interazione dell’utente
• Sistemi automatizzati — job in background, task cron, report automatici
• Fogli di calcolo fissi — controllo di fogli di calcolo specifici
• Ambienti di produzione — funziona in modo affidabile senza flussi di consenso dell’utente

​

Prerequisiti

• Un progetto Google Cloud Console
• Google Sheets API e Google Drive API abilitate
• Permessi di amministratore del progetto

​

Configurazione

1. Crea un progetto Google Cloud

   1. Vai su Google Cloud Console
   2. Crea un nuovo progetto o seleziona uno esistente
   3. Annota l’ID del progetto
2. Abilita le API necessarie

   1. Vai su APIs & Services > Library
   2. Cerca e abilita le seguenti API:
      • Google Sheets API
      • Google Drive API
3. Crea un Service Account

   1. Vai su APIs & Services > Credentials
   2. Fai clic su Create Credentials > Service Account
   3. Inserisci i dettagli del Service Account:
      • Service account name: un nome descrittivo (es. “Laravel Sheets App”)
      • Service account ID: generato automaticamente
      • Description: opzionale
   4. Fai clic su Create and Continue
   5. Salta entrambe le sezioni opzionali e fai clic su Done
4. Genera una chiave del Service Account

   1. Nella pagina Credentials, fai clic sul Service Account creato
   2. Vai alla scheda Keys
   3. Fai clic su Add Key > Create new key
   4. Seleziona JSON come formato della chiave
   5. Fai clic su Create
   6. Il file JSON viene scaricato automaticamente
5. Salva il file JSON

   1. Sposta il file JSON scaricato in storage/app/
   2. Rinominalo in google-service-account.json
   3. Importante: aggiungilo a .gitignore per escluderlo dal controllo di versione

   # Aggiungi a .gitignore
   storage/app/google-service-account.json
   
6. Configura il file .env

   Aggiungi quanto segue a .env:

   GOOGLE_SERVICE_ENABLED=true
   GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
   
7. Imposta gli scope in config/google.php

   'scopes' => [
       \Google\Service\Sheets::SPREADSHEETS,
       \Google\Service\Drive::DRIVE,
   ],
   
8. Condividi il foglio di calcolo

   Per ogni foglio di calcolo di Google Sheets:

   1. Aprilo in Google Sheets
   2. Fai clic sul pulsante Condividi
   3. Copia il campo client_email dal file JSON
   4. Condividi con questo indirizzo email (es. [e-mail])
   5. Seleziona i permessi:
      • Visualizzatore — sola lettura
      • Editor — lettura e scrittura
      • Proprietario — accesso completo (sconsigliato)

​

Utilizzo

Una volta completata la configurazione, il Service Account viene utilizzato automaticamente. Non è necessario impostare un access token.

use Revolution\Google\Sheets\Facades\Sheets;

// Il Service Account viene utilizzato automaticamente
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// Riferimento tramite nome del foglio di calcolo (richiede accesso a Drive API)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

​

Best practice di sicurezza

​

1. Limita i permessi del Service Account

• Condividi solo i fogli di calcolo necessari
• Usa Editor invece di Proprietario
• Verifica periodicamente i permessi di accesso

​

2. Conservazione sicura della chiave

• Non includere la chiave del Service Account nel controllo di versione
• Escludila con certezza tramite .gitignore
• In produzione, conservala in una posizione sicura al di fuori della web root
• Ruota periodicamente le chiavi

​

3. Distribuzione in produzione

Misure di sicurezza aggiuntive:

• Conserva la chiave JSON in una posizione sicura al di fuori della web root
• Usa Service Account diversi per ciascun ambiente (sviluppo, staging, produzione)
• Monitora l’utilizzo di questi account in Google Cloud Console
• Registra e segnala attività sospette

​

Riferimento delle variabili d’ambiente

Variabile	Descrizione	Esempio
GOOGLE_SERVICE_ENABLED	Abilita l’autenticazione Service Account	true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION	Percorso del file JSON	storage/app/google-service-account.json

​

Configurazione avanzata

​

Salvare la stringa JSON in una variabile d’ambiente

Invece di conservare il file JSON come file separato, puoi salvarne il contenuto come variabile d’ambiente. Adatto ad ambienti CI/CD come GitHub Actions.

Step 1: aggiungi la stringa JSON a .env

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

Step 2: decodifica la stringa JSON in config/google.php

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

Con questo metodo non è necessario conservare il file separatamente e puoi gestire tutto tramite le variabili d’ambiente della tua pipeline CI/CD.

​

Risoluzione dei problemi

​

Errori comuni

Errore «caller does not have permission»

• Verifica che il foglio di calcolo sia condiviso con l’indirizzo email del Service Account
• Per le operazioni di scrittura, verifica che i permessi siano almeno Editor

Errore «File not found»

• Verifica che il percorso del file JSON sia corretto
• Verifica che il file esista e sia leggibile dal server web

Errore «API not enabled»

• Verifica che Google Sheets API e Google Drive API siano abilitate in Google Cloud Console
• Attendi qualche minuto dopo l’abilitazione dell’API

Errore «Invalid credentials»

• Verifica che il file della chiave JSON sia valido e non danneggiato
• Verifica che il Service Account non sia stato eliminato o disabilitato
• Verifica che l’ID del progetto corrisponda al progetto Google Cloud

​

Test della configurazione

Una route di test per verificare la configurazione del Service Account:

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

Accedi a questa route di test per verificare che l’autenticazione del Service Account sia configurata correttamente.