Google Sheets API krok po kroku: od dostępu i uwierzytelnienia po przykładowy skrypt

Czym jest Google Sheets API?

Google Sheets API jest częścią ekosystemu Google Workspace i działa w ramach Google Cloud Platform. W praktyce to interfejs RESTful, co oznacza, że komunikacja odbywa się przez standardowe metody HTTP – GET do odczytu danych, POST i PUT do zapisu i aktualizacji. Odpowiedzi z API wracają w formacie JSON, który łatwo przetworzyć w Pythonie czy dowolnym innym języku programowania.

Każdy arkusz Google Sheets posiada unikalny identyfikator (Spreadsheet ID), który znajdziesz w adresie URL arkusza. Wygląda to tak:

https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0

Ten identyfikator jest kluczowym parametrem każdego zapytania do API. Oprócz niego potrzebujesz jeszcze zakresu komórek w tzw. notacji A1 (np. Arkusz1!A1:C10), która wskazuje API, z którego fragmentu arkusza ma pobrać lub do którego zapisać dane.

Z Google Sheets API skorzystasz w zasadzie w każdym języku programowania, natomiast Google oficjalnie wspiera szybki start (quickstart) m.in. dla Pythona, Node.js i Javy. W tym poradniku standardowo korzystamy z Pythona.

Jak uzyskać dostęp do Google Sheets API?

Żeby móc wysyłać zapytania do Google Sheets API, potrzebujesz dwóch rzeczy: włączonej usługi API w ramach projektu Google Cloud oraz danych uwierzytelniających (credentials). Google Cloud oferuje trzy metody autoryzacji:

• OAuth 2.0 – protokół autoryzacji, który pozwala aplikacji działać w imieniu użytkownika. Wymaga interakcji (użytkownik musi zatwierdzić dostęp w przeglądarce). Standardowo używa się go przy łączeniu Sheets czy dowolnych innych produktów z Google Workspace z zewnętrznymi narzędziami (tak będzie np. przy integracji z N8N).
• Service Account (konto usługi) – coś w rodzaju „wirtualnego użytkownika” Google. Działa bez interakcji, idealny do automatyzacji i skryptów uruchamianych cyklicznie (np. w Harmonogramie Windows). Autoryzacja odbywa się plikiem JSON z kluczem prywatnym. Ja łączę się tak z usługami z Google Cloud z przyzwyczajenia i wygody, ponieważ mam już pobrany JSON z uwierzytelnieniami i wystarczy tylko podać jego lokalizację w kodzie.
• Klucz API (API Key) – najprostsza metoda, ale daje wyłącznie dostęp do odczytu publicznych arkuszy. Do większości zastosowań SEO-wych będzie niewystarczający.

W tym poradniku korzystamy z konta usługi (Service Account), ponieważ to najpraktyczniejsza opcja do pracy ze skryptami w Pythonie. Uzyskanie dostępu i pobranie danych uwierzytelniających wygląda identycznie jak w przypadku uzyskiwania dostępu do GSC API. Aby móc korzystać z tej usługi, należy:

1. W otwartym projekcie w konsoli Google Cloud kliknąć w „Interfejsy API i usługi”. Jeżeli nie masz jeszcze projektu w Google Cloud, utwórz go – każdy projekt Google Cloud jest osobnym kontenerem dla konfiguracji API, kluczy i limitów.
2. Kliknąć „Włącz interfejsy API i usługi”.
3. Wpisać w wyszukiwarkę „google sheets api” i kliknąć w wynik.
4. W szczegółach usługi kliknąć „Włącz”. Od tego momentu Google Sheets API jest aktywne w Twoim projekcie i możesz zacząć konfigurować dostęp.
5. Jeżeli nie tworzyliśmy wcześniej kont usługi w Google Cloud, wybrać zakładkę „Dane uwierzytelniające” i po rozwinięciu opcji „Utwórz dane logowania” wybrać „Identyfikator klienta OAuth”. To krok, w którym tworzysz tzw. credentials – zestaw kluczy pozwalających Twojemu skryptowi potwierdzić swoją tożsamość wobec API.
6. Wybrać wartości dla „Typ aplikacji” oraz „Nazwa” i kliknąć „Utwórz”.
7. Jeżeli utworzyliśmy identyfikator lub mieliśmy go wcześniej, w panelu projektu kliknąć hamburger z ustawieniami, tam rozwinąć zakładkę „Administracja” i kliknąć „Konta usługi”. Konto usługi (Service Account) ma własny adres e-mail – to ten adres za chwilę dodasz do arkusza, żeby skrypt mógł go odczytywać i edytować.
8. W panelu „Konta usługi” rozwinąć trzy kropeczki z kolumny „Działania” i kliknąć „Zarządzaj kluczami”.
9. Jeżeli nie mamy pobranego klucza, w panelu zarządzania kluczami rozwinąć opcję „Dodaj klucz” i kliknąć „Utwórz nowy klucz”.
10. W okienku, które wyskoczy, wybrać opcję „JSON” i kliknąć „Utwórz”. Pobrany plik JSON zawiera klucz prywatny Twojego konta usługi – to on pełni rolę access tokena i umożliwia autoryzację bez logowania się w przeglądarce.
11. Zapisać klucz pod zrozumiałą nazwą (np. „kluczapi”). Traktuj ten plik jak hasło – nie udostępniaj go publicznie i nie commituj do repozytorium Git.

Prosty skrypt do Google Sheets API

Standardowo dla moich poradników skorzystamy z Pythona. Do komunikacji z Google Sheets API użyjemy biblioteki gspread – to popularny wrapper w Pythonie, który znacząco upraszcza autoryzację przez Service Account i operacje na arkuszach. Zamiast ręcznie składać zapytania HTTP i parsować JSON-y, wystarczy kilka linijek kodu. Alternatywnie możesz korzystać z oficjalnej biblioteki Google (google-api-python-client), ale gspread jest zdecydowanie wygodniejszy do codziennej pracy.

Przykładowy skrypt wyciągnie treść ze wskazanych adresów URL i umieści ją w stworzonym wcześniej arkuszu. Oczywiście nie jest to nic, czego nie zrobilibyśmy przy pomocy Screaming Froga czy nawet odpowiedniej formuły w samych Sheetsach, ale potraktować warto to jako ćwiczenie do tworzenia bardziej zaawansowanych skryptów.

Aby skorzystać w ten sposób z Google Sheets API, postępuj zgodnie z poniższą instrukcją:

1. Otwórz przygotowany przeze mnie skrypt Google Sheets API w Google Colab.
2. Skopiuj skrypt na swój dysk Google.
3. Przygotuj arkusz Google Sheets z adresami URL do sprawdzenia w kolumnie „URL”.
4. Daj dostęp do edycji arkusza adresowi e-mail konta usługi (Service Account), który znajdziesz w pobranym pliku JSON w polu client_email. Możesz też ustawić dostęp do edycji dla wszystkich posiadających link – ale w przypadku wrażliwych danych lepiej ograniczyć się do konta usługi. To krok kluczowy: bez uprawnień do arkusza skrypt zwróci błąd 403, mimo prawidłowej autoryzacji w Google Cloud.
5. Wczytaj plik JSON z danymi uwierzytelniającymi do pamięci wirtualnej Google Colab.
6. Uzupełnij fragmenty kodu związane z plikiem uwierzytelniającym oraz adresem URL arkusza. W URL-u arkusza znajdziesz Spreadsheet ID – to ciąg znaków między /d/ a /edit.
7. Przystosuj funkcję do wyciągania contentu przy pomocy ChatGPT i kodu strony, którą analizujesz.
8. Odpal kod i sprawdź wyniki w arkuszu.

Limity Google Sheets API

Zanim zaczniesz budować bardziej rozbudowane skrypty, warto znać ograniczenia. Google Sheets API ma limity zapytań (quota), które wynoszą 60 zapytań na minutę na użytkownika i 300 zapytań na minutę na projekt w Google Cloud. Przekroczenie limitów skutkuje błędem 429 (Too Many Requests) i tymczasową blokadą dostępu.

Jeżeli Twój skrypt operuje na wielu arkuszach lub przetwarza dużo danych, warto skorzystać z batch requests – mechanizmu pozwalającego grupować wiele operacji (np. zapis do kilku zakresów komórek) w jedno zapytanie HTTP. Dzięki temu zmieścisz się w limitach i skrypt zadziała szybciej. Alternatywnie możesz dodać do skryptu krótkie opóźnienie (time.sleep()) między kolejnymi zapytaniami.

Aktualne limity zawsze znajdziesz w dokumentacji Google Sheets API.

Google Sheets API a Google Apps Script

Jeżeli nie programujesz w Pythonie, alternatywą jest Google Apps Script – wbudowane środowisko skryptowe dostępne bezpośrednio z poziomu arkusza Google Sheets (menu Rozszerzenia → Apps Script). Apps Script korzysta z JavaScriptu i nie wymaga konfiguracji w Google Cloud Console ani pobierania danych uwierzytelniających – autoryzacja odbywa się automatycznie w kontekście zalogowanego użytkownika.

Kiedy wybrać co? Google Apps Script sprawdzi się przy prostych automatyzacjach wewnątrz arkusza – formatowaniu, tworzeniu menu, reagowaniu na edycje. Google Sheets API jest lepszym wyborem, gdy potrzebujesz integracji z zewnętrznymi narzędziami (np. OpenAI API, bazami danych, narzędziami SEO), pracy z dużymi zbiorami danych lub automatyzacji uruchamianej z serwera albo crona.

Co dalej?

W ten sposób dane są gotowe na przykład do przeanalizowania przez OpenAI API pod wskazanym w prompcie kątem lub obliczenia osadzeń wektorowych, a następnie podobieństwa cosinusowego poszczególnych treści. Google Sheets API świetnie sprawdza się również jako warstwa pośrednia między scrapowaniem danych a ich dalszym przetwarzaniem – arkusz pełni wtedy funkcję lekkiej bazy danych dostępnej z poziomu dowolnego skryptu. Szczerze powiem jednak, że te wszystkie limity oraz konieczność ich pilnowania sprawiły, że staram się unikać integracji z Sheetsami jak ognia i korzystam z self-hostowanej bazy w NocoDB.

Warto też pamiętać, że jeśli Twój skrypt operuje nie tylko na zawartości arkusza, ale też na samych plikach (tworzenie, przenoszenie, zmiana uprawnień), będziesz potrzebować dodatkowo Google Drive API – oba interfejsy uzupełniają się wzajemnie. O tym jednak w oddzielnych poradnikach.

Te artykuły powinny Cię zainteresować

1. Custom Search API krok po kroku
2. GSC na sterydach: wykorzystaj API GSC, BigQuery, Looker Studio i Screaming Froga
3. Jak korzystać z API z Google Cloud?
4. PageSpeed Insights API krok po kroku
5. Poradnik Natural Language API krok po kroku

O autorze

Nazywam się Michał Małysa i od wielu lat zajmuję się zawodowo SEO oraz analizą treści, a od 2023 roku w zakres moich obowiązków i zainteresowań dość naturalnie weszło AI. Na stronie MałySEO porządkuję wiedzę o pozycjonowaniu stron internetowych, AI Search oraz działaniu LLM-ów. Prowadzę również MałySEO Newsletter, do którego subskrypcji serdecznie Cię zachęcam na podstronie najlepszego w Polsce newslettera SEO.

Jako że przygotowanie materiałów do MałySEO Newslettera oraz na bloga zajmuje nieco czasu, może zaświtać Ci w głowie dość miły z mojej perspektywy pomysł drobnego rewanżu. Jeżeli uznasz, że lektura tego wpisu była dla Ciebie czymś więcej, niż tylko szybkim odklepaniem randomowej internetowej treści, możesz postawić mi kawkę na buycoffee.to. Z góry dziękuję!

Jeżeli z jakiegoś powodu potrzebujesz się ze mną skontaktować, wyślij mail na adres kontakt[at]michalmalysa.pl