Come collegare Google Sheets alla tua app

Per collegare Google Sheets alla tua app, abiliti l'API Google Sheets in un progetto di Google Cloud, crei un service account, condividi il foglio con l'indirizzo email del service account e salvi la sua chiave come segreto lato server. Il tuo server legge le righe con spreadsheets.values.get e ne aggiunge con spreadsheets.values.append. Se gli utenti devono collegare i propri fogli, usa invece OAuth; se il foglio è completamente pubblico, per la sola lettura basta una semplice chiave API.

Questa guida spiega quale metodo scegliere, le chiamate necessarie, le quote e le insidie, e come formulare i prompt per un app builder basato sull'AI. I dettagli su Google provengono dalla documentazione per sviluppatori di Google aggiornata a settembre 2026.

Perché collegare un foglio

Motivi comuni:

• Mantenere il flusso di lavoro del team. Lo staff continua a modificare un listino o un calendario in Sheets; l'app lo mostra.
• Raccogliere dati dove le persone guardano già. Nuove iscrizioni, ordini o risposte ai moduli finiscono come righe.
• Reportistica. Esportare i dati dell'app in un foglio per chi lavora abitualmente con i fogli di calcolo.
• Un trampolino. Partire dal foglio, poi passare a un database vero. Vedi come trasformare un foglio di calcolo in un'app.

Scegli come la tua app si autentica con Google

La guida alle credenziali di Google descrive tre tipi:

Per la maggior parte delle app il service account è la scelta giusta: un unico set di credenziali, di tua proprietà, con accesso solo ai fogli che condividi esplicitamente con esso.

Passo per passo con un service account

1. Crea o scegli un progetto Google Cloud e abilita l'API Google Sheets.
2. Crea un service account e una chiave per esso. La chiave è un file JSON; trattala come una password.
3. Condividi il foglio con l'indirizzo email del service account, come Visualizzatore per la sola lettura o come Editor per scrivere. La guida di Google dice che si fa dalla normale schermata di condivisione.
4. Salva la chiave come segreto sul tuo server, per esempio GOOGLE_SERVICE_ACCOUNT_JSON, e l'ID del foglio (la lunga stringa nell'URL del foglio) come SHEET_ID.
5. Chiama l'API dal server con la libreria client di Google per il tuo linguaggio.
6. Metti in cache le letture se molti visitatori vedono gli stessi dati, così non superi la quota.

Le chiamate che userai

Dalla guida di Google alla lettura e scrittura dei valori:

Gli intervalli usano la notazione A1. Google fa notare che un intervallo senza nome del foglio, come A1:B2, si applica al primo foglio, quindi indica sempre esplicitamente la scheda per evitare sorprese quando qualcuno riordina le schede.

RAW vs USER_ENTERED

Le scritture richiedono un valueInputOption:

• RAW memorizza esattamente ciò che invii, come testo. =1+2 viene salvato come il testo =1+2.
• USER_ENTERED tratta l'input come se fosse digitato in Sheets: le date diventano date e =1+2 diventa una formula.

Se scrivi testo digitato dagli utenti della tua app, usa RAW. Con USER_ENTERED, qualcuno potrebbe inviare una formula che viene eseguita quando un collega apre il foglio.

Quote ed errori

A settembre 2026, la pagina dei limiti dell'API Sheets di Google riporta:

Non c'è un limite giornaliero finché rimani entro le quote al minuto. Superarle restituisce 429: Too many requests, e Google consiglia il backoff esponenziale troncato: attendi più a lungo dopo ogni tentativo fallito, con un ritardo casuale, fino a un massimo. Una singola richiesta che supera i 180 secondi va in timeout.

In pratica: non chiamare l'API a ogni visualizzazione di pagina. Metti in cache i dati del foglio per un minuto o più, raggruppa le letture con batchGet e raggruppa le scritture dove possibile.

Opzioni e compromessi

Per qualsiasi cosa con molti utenti o dati sensibili, un database è la fonte di verità migliore. Vedi cos'è un database.

Prompt da dare al tuo app builder AI

Lettura di un foglio:

Mostra la scheda «Menu» del nostro foglio Google nella pagina del menu. Usa l'API Google Sheets dal server con un service account la cui chiave JSON è nel segreto GOOGLE_SERVICE_ACCOUNT_JSON, e l'ID del foglio in SHEET_ID. Leggi l'intervallo Menu!A2:D (nome, descrizione, prezzo, categoria). Metti in cache il risultato per 5 minuti. Se l'API fallisce, mostra l'ultima versione in cache. Non inviare mai la chiave al browser.

Scrittura di righe:

Quando qualcuno invia il modulo di contatto, salvalo nel nostro database e aggiungi anche una riga alla scheda «Contatti» (data, nome, email, messaggio) con spreadsheets.values.append e valueInputOption RAW. Se Google restituisce 429, riprova con backoff esponenziale; se fallisce ancora, conserva il contatto nel database e riprova più tardi.

Errori comuni

• Dimenticare di condividere il foglio con l'email del service account. L'API restituisce allora un errore di permessi anche se la chiave è corretta.
• Chiave nel frontend o nel repository. La chiave JSON concede accesso a ogni foglio condiviso con essa. Vedi come proteggere le chiavi API.
• Usare USER_ENTERED per l'input degli utenti, che consente l'iniezione di formule.
• Chiamare l'API a ogni richiesta e superare la quota al minuto al primo picco di traffico.
• Dipendere dalla posizione delle colonne. Qualcuno inserisce una colonna e l'app legge i dati sbagliati. Leggi la riga di intestazione e mappa per nome, oppure blocca l'intestazione.
• Condividere il foglio più di quanto serva. «Chiunque abbia il link» lo rende pubblico.
• Usare un foglio come database multiutente. Scritture concorrenti e permessi mancanti causano perdite o fughe di dati.

Checklist

• API Sheets abilitata; service account creato
• Foglio condiviso con l'email del service account con il ruolo minimo necessario
• Chiave e ID del foglio salvati come segreti lato server
• Tutte le chiamate fatte dal server
• Nomi delle schede usati negli intervalli
• RAW usato per il testo fornito dagli utenti
• Letture in cache; 429 gestito con backoff
• L'app degrada in modo corretto se Sheets non è disponibile
• Deciso quale lato è la fonte di verità

Google Sheets in Mythex

Su Mythex ci sono due modi diversi per lavorare con Sheets. I connettori collegano il tuo account Google a Mythex così che l'agente possa usarlo mentre costruisci, per esempio leggendo un foglio per creare una dashboard; la documentazione dice che la credenziale resta presso il servizio di connessione di Mythex e non finisce mai nel tuo codice (vedi Connettori, e approva ogni permesso richiesto da Google). Perché l'app pubblicata legga o scriva un foglio da sola, la strada affidabile è quella di questa guida: una chiave di service account salvata come segreto del progetto e chiamate all'API Sheets dal tuo server, come in Integrare qualsiasi API. Se stai superando il foglio, chiedi all'agente di spostare i dati nel database del progetto e costruire una dashboard sopra di esso.

Domande