Cum conectezi Google Sheets la aplicația ta

Ca să conectezi Google Sheets la aplicația ta, activezi Google Sheets API într-un proiect Google Cloud, creezi un cont de serviciu, partajezi tabelul cu adresa de e-mail a contului de serviciu și păstrezi cheia lui ca secret pe server. Serverul tău citește apoi rândurile cu spreadsheets.values.get și adaugă rânduri cu spreadsheets.values.append. Dacă utilizatorii trebuie să-și conecteze propriile tabele, folosești OAuth, iar dacă tabelul este complet public, pentru citire ajunge o simplă cheie API.

Ghidul acoperă ce metodă se potrivește, apelurile de care ai nevoie, limitele și capcanele, precum și prompturi pentru un constructor de aplicații cu AI. Detaliile Google provin din documentația pentru dezvoltatori a Google, la septembrie 2026.

De ce să conectezi un tabel

Motive obișnuite:

• Să păstrezi fluxul de lucru al echipei. Colegii continuă să editeze o listă de prețuri sau un program în Sheets; aplicația îl afișează.
• Să colectezi date acolo unde oamenii se uită deja. Înscrierile noi, comenzile sau răspunsurile la formulare ajung ca rânduri.
• Raportare. Exporți datele aplicației într-un tabel pentru oamenii care lucrează zilnic în tabele.
• O treaptă intermediară. Pornești de la tabel și treci apoi la o bază de date adevărată. Vezi cum transformi un tabel într-o aplicație.

Alege cum se autentifică aplicația ta la Google

Ghidul Google despre credențiale descrie trei tipuri:

Pentru majoritatea aplicațiilor, contul de serviciu este alegerea potrivită: un set de credențiale, deținut de tine, cu acces doar la tabelele pe care le partajezi explicit cu el.

Pas cu pas, cu un cont de serviciu

1. Creează sau alege un proiect Google Cloud și activează API-ul Google Sheets.
2. Creează un cont de serviciu și o cheie pentru el. Cheia este un fișier JSON; tratează-o ca pe o parolă.
3. Partajează tabelul cu adresa de e-mail a contului de serviciu, ca Viewer pentru citire sau Editor pentru scriere. Ghidul Google spune că asta se face din ecranul obișnuit de partajare.
4. Păstrează cheia ca secret pe serverul tău, de exemplu GOOGLE_SERVICE_ACCOUNT_JSON, plus ID-ul tabelului (șirul lung din URL-ul tabelului) ca SHEET_ID.
5. Apelează API-ul de pe server cu biblioteca clientă Google pentru limbajul tău.
6. Pune citirile în cache dacă mulți vizitatori văd aceleași date, ca să nu atingi limita.

Apelurile pe care le vei folosi

Din ghidul Google pentru citirea și scrierea valorilor:

Intervalele folosesc notația A1. Google notează că un interval fără numele foii, cum este A1:B2, se aplică primei foi, așa că numește explicit fila ca să eviți surprize când cineva reordonează filele.

RAW vs USER_ENTERED

Scrierile au nevoie de un valueInputOption:

• RAW stochează exact ce trimiți, ca text. =1+2 este salvat ca textul =1+2.
• USER_ENTERED tratează intrarea ca și cum ar fi fost tastată în Sheets: datele devin date, iar =1+2 devine o formulă.

Dacă scrii text pe care utilizatorii l-au tastat în aplicația ta, folosește RAW. Cu USER_ENTERED, cineva ar putea trimite o formulă care se execută când un coleg deschide tabelul.

Limite și erori

La septembrie 2026, pagina de limite a API-ului Sheets de la Google listează:

Nu există limită zilnică, atâta timp cât rămâi în limitele pe minut. Depășirea lor întoarce 429: Too many requests, iar Google recomandă backoff exponențial trunchiat: aștepți tot mai mult după fiecare încercare eșuată, cu o întârziere aleatorie, până la un maxim. O cerere unică care durează peste 180 de secunde expiră.

În practică: nu apela API-ul la fiecare vizualizare de pagină. Ține datele tabelului în cache un minut sau mai mult, grupează citirile cu batchGet și grupează scrierile acolo unde poți.

Opțiuni și compromisuri

Pentru orice cu mulți utilizatori sau date sensibile, o bază de date este sursa de adevăr mai bună. Vezi ce este o bază de date.

Prompturi pentru constructorul tău AI

Citirea unui tabel:

Arată fila „Menu” din tabelul nostru Google Sheets pe pagina de meniu. Folosește API-ul Google Sheets de pe server, cu un cont de serviciu a cărui cheie JSON este în secretul GOOGLE_SERVICE_ACCOUNT_JSON, iar ID-ul tabelului în SHEET_ID. Citește intervalul Menu!A2:D (nume, descriere, preț, categorie). Ține rezultatul în cache 5 minute. Dacă API-ul eșuează, arată ultima versiune din cache. Nu trimite niciodată cheia în browser.

Scrierea rândurilor:

Când cineva trimite formularul de contact, salvează-l în baza noastră de date și adaugă și un rând în fila „Leads” (dată, nume, e-mail, mesaj), folosind spreadsheets.values.append cu valueInputOption RAW. Dacă Google întoarce 429, reîncearcă cu backoff exponențial; dacă tot eșuează, păstrează lead-ul în baza de date și reîncearcă mai târziu.

Greșeli frecvente

• Uitatul de a partaja tabelul cu adresa de e-mail a contului de serviciu. API-ul întoarce atunci o eroare de permisiune, deși cheia este corectă.
• Cheia în frontend sau în repository. Cheia JSON dă acces la fiecare tabel partajat cu ea. Vezi cum păstrezi în siguranță cheile API.
• Folosirea USER_ENTERED pentru datele introduse de utilizatori, ceea ce permite injectarea de formule.
• Apelarea API-ului la fiecare cerere și atingerea limitei pe minut la primul vârf de trafic.
• Dependența de pozițiile coloanelor. Cineva inserează o coloană și aplicația citește date greșite. Citește rândul de antet și mapează după nume sau blochează antetul.
• Partajarea tabelului mai larg decât e nevoie. „Oricine are linkul” îl face public.
• Folosirea unui tabel ca bază de date cu mulți utilizatori. Scrierile concurente și permisiunile lipsă duc la pierderi sau scurgeri de date.

Listă de verificare

• API-ul Sheets activat; cont de serviciu creat
• Tabelul partajat cu adresa de e-mail a contului de serviciu, cu rolul minim necesar
• Cheia și ID-ul tabelului păstrate ca secrete pe server
• Toate apelurile făcute de pe server
• Numele filelor folosite în intervale
• RAW folosit pentru textul furnizat de utilizatori
• Citirile în cache; 429 tratat cu backoff
• Aplicația se degradează elegant dacă Sheets nu este disponibil
• Decis care parte este sursa de adevăr

Google Sheets în Mythex

Mythex are două moduri diferite de a lucra cu Sheets. Conectorii leagă contul tău Google de Mythex, ca agentul să-l poată folosi cât construiești, de exemplu citind un tabel ca să construiască din el un dashboard. Documentația spune că acreditarea rămâne la serviciul de conexiune al Mythex și nu ajunge niciodată în codul tău (vezi Conectori, și aprobă fiecare permisiune cerută de Google). Pentru ca aplicația publicată să citească sau să scrie singură într-un tabel, varianta sigură este cea din acest ghid: o cheie de cont de serviciu păstrată ca secret al proiectului și apeluri API Sheets de pe serverul tău, ca în Integrează orice API. Dacă depășești tabelul, cere agentului să mute datele în baza de date a proiectului și să construiască un dashboard deasupra lor.

Întrebări