Jak połączyć Arkusze Google z aplikacją

Aby połączyć Arkusze Google z aplikacją, włączasz Google Sheets API w projekcie Google Cloud, tworzysz konto usługi, udostępniasz arkusz adresowi e-mail tego konta i przechowujesz jego klucz jako sekret po stronie serwera. Serwer odczytuje wiersze za pomocą spreadsheets.values.get i dodaje je przez spreadsheets.values.append. Jeśli użytkownicy mają łączyć swoje arkusze, użyj zamiast tego OAuth, a gdy arkusz jest w pełni publiczny, do samego odczytu wystarczy prosty klucz API.

Ten poradnik opisuje, która metoda pasuje, jakie wywołania są potrzebne, limity i pułapki oraz gotowe prompty dla narzędzia do budowy aplikacji z AI. Szczegóły Google pochodzą z dokumentacji dla deweloperów Google, stan na wrzesień 2026.

Po co w ogóle łączyć arkusz

Najczęstsze powody:

• Zachowanie workflow zespołu. Pracownicy nadal edytują cennik lub grafik w Arkuszach, a aplikacja go wyświetla.
• Zbieranie danych tam, gdzie ludzie już patrzą. Nowe rejestracje, zamówienia lub odpowiedzi z formularzy trafiają jako wiersze.
• Raportowanie. Eksport danych aplikacji do arkusza dla osób, które na co dzień pracują w arkuszach kalkulacyjnych.
• Etap przejściowy. Zacznij od arkusza, a potem przejdź na porządną bazę danych. Zobacz jak zamienić arkusz kalkulacyjny w aplikację.

Wybierz, jak aplikacja loguje się do Google

Przewodnik Google o uwierzytelnianiu opisuje trzy typy:

W większości aplikacji właściwym wyborem jest konto usługi: jeden zestaw danych uwierzytelniających, należący do Ciebie, z dostępem tylko do arkuszy, które jawnie mu udostępnisz.

Krok po kroku z kontem usługi

1. Utwórz lub wybierz projekt Google Cloud i włącz Google Sheets API.
2. Utwórz konto usługi i jego klucz. Klucz to plik JSON; traktuj go jak hasło.
3. Udostępnij arkusz adresowi e-mail konta usługi: jako Czytelnik, jeśli tylko odczytujesz, lub jako Edytor, jeśli zapisujesz. Przewodnik Google mówi, że robi się to zwykłym oknem udostępniania.
4. Zapisz klucz jako sekret na serwerze, na przykład GOOGLE_SERVICE_ACCOUNT_JSON, a identyfikator arkusza (długi ciąg w adresie URL arkusza) jako SHEET_ID.
5. Wywołuj API z serwera za pomocą biblioteki klienckiej Google dla Twojego języka.
6. Buforuj odczyty, jeśli wielu odwiedzających widzi te same dane, żebyś nie uderzał w limit.

Wywołania, których użyjesz

Z przewodnika Google po odczycie i zapisie wartości:

Zakresy używają notacji A1. Google zaznacza, że zakres bez nazwy arkusza, jak A1:B2, odnosi się do pierwszego arkusza, więc nazwij kartę jawnie, aby uniknąć niespodzianek, gdy ktoś zmieni kolejność kart.

RAW kontra USER_ENTERED

Zapisy wymagają valueInputOption:

• RAW zapisuje dokładnie to, co wyślesz, jako tekst. =1+2 zostaje zapisane jako tekst =1+2.
• USER_ENTERED traktuje dane tak, jakby wpisano je w Arkuszach: daty stają się datami, a =1+2 staje się formułą.

Jeśli zapisujesz tekst wpisany przez użytkowników w aplikacji, użyj RAW. Przy USER_ENTERED ktoś może przesłać formułę, która uruchomi się, gdy kolega otworzy arkusz.

Limity i błędy

Stan na wrzesień 2026: strona limitów Sheets API Google podaje:

Nie ma limitu dziennego, o ile mieścisz się w limitach na minutę. Przekroczenie zwraca 429: Too many requests, a Google zaleca obcinany wykładniczy backoff: po każdej nieudanej próbie czekaj dłużej, z losowym opóźnieniem, do pewnego maksimum. Pojedyncze żądanie trwające ponad 180 sekund kończy się przekroczeniem czasu.

W praktyce: nie wywołuj API przy każdym wyświetleniu strony. Buforuj dane arkusza przez minutę lub dłużej, grupuj odczyty przez batchGet i grupuj zapisy tam, gdzie się da.

Opcje i kompromisy

Dla wszystkiego z wieloma użytkownikami lub wrażliwymi danymi lepszym źródłem prawdy jest baza danych. Zobacz czym jest baza danych.

Prompty dla narzędzia do budowy z AI

Odczyt arkusza:

Pokaż kartę „Menu” naszego Arkusza Google na stronie z menu. Użyj Google Sheets API z serwera, z kontem usługi, którego klucz JSON jest w sekrecie GOOGLE_SERVICE_ACCOUNT_JSON, a identyfikator arkusza w SHEET_ID. Odczytaj zakres Menu!A2:D (nazwa, opis, cena, kategoria). Zapisz wynik w pamięci podręcznej na 5 minut. Jeśli API zawiedzie, pokaż ostatnią zapisaną wersję. Nigdy nie wysyłaj klucza do przeglądarki.

Zapis wierszy:

Gdy ktoś wyśle formularz kontaktowy, zapisz go w naszej bazie danych i dodaj wiersz do karty „Leady” (data, imię, e-mail, wiadomość), używając spreadsheets.values.append z valueInputOption RAW. Jeśli Google zwróci 429, ponów próbę z wykładniczym backoffem; jeśli nadal się nie uda, zachowaj lead w bazie danych i ponów później.

Częste błędy

• Zapomnienie o udostępnieniu arkusza adresowi e-mail konta usługi. API wtedy zwraca błąd uprawnień, mimo że klucz jest poprawny.
• Klucz we frontendzie lub w repozytorium. Klucz JSON daje dostęp do każdego arkusza udostępnionego temu kontu. Zobacz jak bezpiecznie przechowywać klucze API.
• Używanie USER_ENTERED dla danych wpisanych przez użytkowników, co pozwala na wstrzyknięcie formuły.
• Wywoływanie API przy każdym żądaniu i trafienie w limit na minutę przy pierwszym skoku ruchu.
• Poleganie na pozycjach kolumn. Ktoś wstawi kolumnę i aplikacja odczyta złe dane. Czytaj wiersz nagłówka i mapuj po nazwie albo zablokuj nagłówek.
• Udostępnianie arkusza szerzej, niż trzeba. „Każdy, kto ma link” czyni go publicznym.
• Używanie arkusza jako wielodostępowej bazy danych. Równoczesne zapisy i brakujące uprawnienia prowadzą do utraty lub wycieku danych.

Lista kontrolna

• Włączone Sheets API; utworzone konto usługi
• Arkusz udostępniony adresowi e-mail konta usługi z najniższą potrzebną rolą
• Klucz i identyfikator arkusza zapisane jako sekrety po stronie serwera
• Wszystkie wywołania wykonywane z serwera
• W zakresach używane nazwy kart
• RAW używane dla tekstu podanego przez użytkownika
• Odczyty buforowane; błąd 429 obsłużony backoffem
• Aplikacja działa w trybie ograniczonym, gdy Arkusze są niedostępne
• Ustalono, która strona jest źródłem prawdy

Arkusze Google w Mythex

Mythex ma dwa różne sposoby pracy z Arkuszami. Konektory łączą Twoje konto Google z Mythex, tak aby agent mógł z niego korzystać podczas budowy, na przykład odczytując arkusz, by zbudować z niego pulpit. Dokumentacja mówi, że dane uwierzytelniające pozostają w usłudze połączeń Mythex i nigdy nie trafiają do Twojego kodu (zobacz Connectors i zatwierdzaj każde uprawnienie, o które prosi Google). Aby opublikowana aplikacja sama odczytywała lub zapisywała arkusz, niezawodną drogą jest ta z tego poradnika: klucz konta usługi zapisany jako sekret projektu i wywołania Sheets API z serwera, tak jak w Integrate any API. Jeśli wyrastasz z arkusza, poproś agenta o przeniesienie danych do bazy danych projektu i zbudowanie na niej pulpitu.

Pytania