Samouczek: Google Apps Script i Gemini API — inteligentne wyodrębnianie danych

Ręczne wprowadzanie danych to wróg produktywności. Jeśli twój zespół polega na wyciąganiu danych z e‑maili operacyjnych, takich jak faktury, potwierdzenia rezerwacji czy formularze opinii klientów, prawdopodobnie znasz koszmar tradycyjnych metod parsowania. 

Historycznie programiści używali wyrażeń regularnych (Regex), aby wyłuskać szczegóły, takie jak numery faktur czy kwoty rozliczeń. Ale Regex jest niezwykle kruchy; w momencie, gdy dostawca zmieni szablon e‑maila lub doda przypadkowy podział wiersza, cały parser po cichu się sypie.

W tym tutorialu pokażę ci, jak zbudować w pełni zautomatyzowany, bezgłowy pipeline rozwiązujący ten problem z użyciem generatywnej AI. Napiszemy lekki skrypt, który czyta nieprzeczytane wiadomości Gmail, przekazuje niestrukturyzowany tekst do Gemini API do inteligentnej ekstrakcji i zapisuje idealnie ustrukturyzowane dane JSON bezpośrednio w Arkuszu Google.

Wymagania wstępne:

• Konto Google
• Podstawowa znajomość JavaScript (Google Apps Script)
• Klucz API Gemini

Czym jest Google Apps Script?

Google Apps Script to oparte na JavaScript, chmurowe środowisko szybkiego tworzenia aplikacji, które pozwala automatyzować, dostosowywać i rozszerzać aplikacje Google Workspace, takie jak Dokumenty, Arkusze, Prezentacje i nie tylko. 

Ponieważ platforma działa bezpośrednio na serwerach Google, nie musisz instalować oprogramowania, konfigurować środowisk lokalnych ani zarządzać infrastrukturą. 

Apps Script daje programistom i twórcom low‑code możliwość programowego kontaktu z narzędziami Google Workspace, takimi jak Dokumenty, Arkusze, Prezentacje, Dysk i inne. Możesz budować i uruchamiać automatyzacje poprzez niestandardowe menu, przyciski lub harmonogramy czasowe, a także tworzyć i publikować dodatki do Google Workspace Marketplace.

Jak działa Google Apps Script

Google Apps Script odciąża cię od żmudnej konfiguracji backendu i uwierzytelniania API, pozwalając skupić się na logice i danych. Robi to dzięki kilku funkcjom:

• Edytor natywny dla chmury: Piszesz, debugujesz i wdrażasz kod JavaScript całkowicie w przeglądarkowym IDE.
• Usługi wbudowane: Zamiast zmagać się z OAuth i złożonymi wywołaniami API, używasz gotowych globalnych obiektów (takich jak SpreadsheetApp, MailApp czy DriveApp), aby natywnie współpracować z usługami Google.
• Wyzwalacze zdarzeniowe: Skrypty można uruchamiać ręcznie z poziomu niestandardowych przycisków w menu lub planować automatyczne uruchamianie za pomocą wyzwalaczy czasowych (np. o północy) i zdarzeniowych (np. po wysłaniu Formularza Google).

Architektura Google Apps Script: pipeline od Gmaila do Arkuszy

Zanim napiszemy skrypt, prześledźmy przepływ danych w tym pipeline. Architektura opiera się na czterech odrębnych komponentach współpracujących ze sobą:

• Gmail (źródło): Proces zaczyna się od zapytania skrzynki odbiorczej z użyciem standardowych operatorów wyszukiwania (np. is:unread label:invoices). Skrypt izoluje właściwe wątki i wyciąga zarówno treść w formacie txt, jak i załączone pliki PDF.
• Apps Script (obliczenia): Działa jako warstwa orkiestracji. Iteruje po nieprzeczytanych wątkach, formatuje załączniki do danych base64 i obsługuje logikę raportowania błędów oraz przetwarzania wsadowego.
• Gemini API (silnik transformacji): Apps Script wysyła multimodalny ładunek (tekst e‑maila plus PDF‑y) do modelu Gemini 2.5 Flash. Przekazując w wywołaniu API rygorystyczny schemat odpowiedzi JSON, wymuszamy na modelu wyciągnięcie dokładnych wartości, takich jak dostawca, kwota całkowita i waluta, zamiast generowania tekstu konwersacyjnego.
• Arkusze Google (cel): Gdy Gemini zwraca ustrukturyzowany JSON, Apps Script parsuje wyniki, pakuje je w jedną tablicę i hurtowo wstawia dane do następnego pustego wiersza aktywnego arkusza za pomocą setValues().

Dlaczego użyć Google Apps Script jako warstwy obliczeniowej?

Główną korzyścią jest całkowite wyeliminowanie narzutu infrastrukturalnego. Nie ma potrzeby przygotowywania serwerów, konfigurowania kontenerów Dockera ani ustawiania skomplikowanych przepływów OAuth tylko po to, by czytać e‑maile czy pisać do arkusza.

Ponieważ Apps Script natywnie integruje się z usługami takimi jak GmailApp i SpreadsheetApp, Google obsługuje uwierzytelnianie wewnętrznie. Ty po prostu piszesz kod i łączysz końcówki.

Krok 1: Przygotuj środowisko Google Apps Script

Zanim napiszemy kod, przygotujmy zależności zewnętrzne. Obejmuje to uzyskanie dostępu do Gemini API, utworzenie docelowego arkusza kalkulacyjnego oraz skonfigurowanie Gmaila, by odpowiednio tagował przychodzące faktury.

Generowanie klucza Gemini API

Aby zasilić inteligentne wyodrębnianie danych, potrzebujemy dostępu do Gemini API.

1. Przejdź do Google AI Studio i zaloguj się na konto Google.
2. W menu po lewej kliknij Get API key.
3. Kliknij przycisk Create API key. Możesz utworzyć klucz w istniejącym projekcie Google Cloud lub pozwolić AI Studio stworzyć nowy.
4. Skopiuj wygenerowany ciąg. 

Najlepsze praktyki bezpieczeństwa: Nie zgub tego klucza, ale co ważniejsze — nie planuj umieszczać go w kodzie w postaci zwykłego tekstu. Na razie trzymaj go w schowku lub bezpiecznym notatniku; w następnym kroku bezpiecznie zamkniemy go w środowisku Apps Script.

Przygotowanie Arkusza Google i zabezpieczenie klucza

Potrzebujemy miejsca na przechowywanie wyodrębnionych danych. Ten arkusz będzie też punktem startowym dla naszego skryptu automatyzującego.

1. Ustaw nagłówki bazy danych Utwórz nowy, pusty Arkusz Google. W pierwszym wierszu dodaj poniższe nagłówki kolumn, aby odpowiadały schematowi JSON, który zdefiniujemy w skrypcie:

• Date
• Vendor
• Invoice Number
• Total Amount
• Currency
• Items Summary
• Email Link

Zablokuj (zamroź) górny wiersz, aby nagłówki były zawsze widoczne wraz z rozrostem danych.

2. Przejdź do Apps Script i zapisz klucz API Skoro arkusz już istnieje, możemy otworzyć edytor Apps Script bezpośrednio z jego poziomu. To automatycznie powiąże nasz kod z tym konkretnym arkuszem.

1. W Arkuszu Google kliknij Rozszerzenia > Apps Script w górnym menu.
2. Gdy edytor się otworzy, spójrz na lewy pasek boczny i kliknij ikonę koła zębatego, aby otworzyć Ustawienia projektu.

3. Przewiń na dół, aby znaleźć sekcję Właściwości skryptu (Script Properties).
4. Kliknij Add script property.
5. W polu Property wpisz dokładnie GEMINI_API_KEY.
6. W polu Value wklej klucz API skopiowany wcześniej z AI Studio.
7. Kliknij Save script properties.

Kod, który napiszemy później, pobierze teraz bezpiecznie tę wartość w czasie działania, nie ujawniając twoich poświadczeń.

Krok 2: Napisz kod Google Apps Script

Będąc w edytorze Apps Script, usuń domyślny kod. Zbudujemy nasz silnik automatyzacji krok po kroku.

1. Konfiguracja i ustawienie interfejsu

Zaczynamy od zdefiniowania globalnego obiektu konfiguracyjnego. To dobra praktyka czystego kodu, która grupuje wszystkie wartości stałe w jednym miejscu, więc edytujesz tylko ten górny blok.

Dodajemy też funkcję onOpen(). Ten wbudowany wyzwalacz Apps Script automatycznie tworzy niestandardowe menu w twoim Arkuszu Google, co pozwala nietechnicznym użytkownikom uruchamiać skrypt ręcznie, bez otwierania edytora kodu.

const CONFIG = {
 searchQuery: "is:unread label:invoices",
 model: "gemini-2.5-flash",
 adminEmail: Session.getActiveUser().getEmail() // Automatically emails the script owner if it crashes
};

/**
* Creates a custom menu in Google Sheets so non-technical users can run the script manually.
*/
function onOpen() {
 const ui = SpreadsheetApp.getUi();
 ui.createMenu('🤖 AI Automations')
   .addItem('Fetch New Invoices', 'processInvoices')
   .addToUi();
}

2. Ustawienie orkiestracji

Funkcja processInvoices() działa jako główny orkiestrator. Zaczyna od bezpiecznego pobrania klucza API z Właściwości skryptu, które ustawiliśmy wcześniej. 

Następnie używa wbudowanej usługi GmailApp do zapytania skrzynki.

Wywołując GmailApp.search(CONFIG.searchQuery), skrypt pobiera tablicę wątków e‑mail, które pasują do reguły is:unread label:invoices. 

Jeśli znajdzie dopasowania, przechodzi przez każdy wątek, pobiera najnowszą wiadomość, wyciąga treść w formacie txt i wyodrębnia załączone pliki PDF.

function processInvoices() {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  if (!apiKey) {
    throw new Error("GEMINI_API_KEY is missing! Please set it in Script Properties.");
  }

  const threads = GmailApp.search(CONFIG.searchQuery);
  if (threads.length === 0) return;

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const batchData = [];
  const processedThreads = [];

3. Przetwarzanie e‑maili i multimodalnych PDF‑ów

Podczas iteracji po wątkach pobieramy najnowszą wiadomość. Jednak faktury rzadko przychodzą jako zwykły tekst; niemal zawsze są załączone jako PDF‑y. 

Wykorzystując Gemini 2.5 Flash, który jest natywnie multimodalny, nasz skrypt przechodzi po latestMessage.getAttachments(), zbiera wszystkie PDF‑y, konwertuje je do ciągu Base64 i przekazuje bezpośrednio do ładunku API jako inlineData. 

Gemini „czyta” PDF wizualnie i wyodrębnia dane tak samo łatwo jak tekst.

for (let i = 0; i < threads.length; i++) {
   const thread = threads[i];
   const latestMessage = thread.getMessages().pop();
  
   const emailBody = latestMessage.getPlainBody();
   const emailDate = latestMessage.getDate();
   const emailLink = https://mail.google.com/mail/u/0/#inbox/${thread.getId()};
   const attachments = latestMessage.getAttachments();
   try {
     const geminiParts = [];
     geminiParts.push({ text: "Extract invoice details from this email and any attached documents:\n\n" + emailBody });
    
     // Add PDF attachments as base64 to the prompt
     for (const attachment of attachments) {
       if (attachment.getContentType() === "application/pdf") {
         geminiParts.push({
           inlineData: {
             mimeType: "application/pdf",
             data: Utilities.base64Encode(attachment.getBytes())
           }
         });
       }
     }
     // Invoke Gemini API
     const extractedData = callGeminiAPI(apiKey, geminiParts);

4. Wstawianie wsadowe i obsługa błędów

Aby zoptymalizować wydajność, nie zapisujemy do arkusza wiersz po wierszu. 

Zamiast tego wrzucamy wyodrębnione dane JSON do tablicy (batchData) i zapisujemy wszystko jednorazowo na końcu, używając setValues().

Zwróć uwagę na blok try...catch. 

Jeśli Gemini popłynie lub zawiedzie na konkretnym e‑mailu, skrypt nie zawiesza się w całości. Zamiast tego elegancko przechwytuje błąd i używa MailApp.sendEmail(), aby natychmiast powiadomić administratora, zapewniając wysoką obserwowalność.

 // Push to batch array instead of writing one-by-one
     batchData.push([
       emailDate,
       extractedData.vendor || "Unknown Vendor",
       extractedData.invoiceNumber || "N/A",
       extractedData.totalAmount || 0.00,
       extractedData.currency || "USD",
       extractedData.itemsSummary || "N/A",
       emailLink
     ]);
     processedThreads.push(thread);
   } catch (error) {
     MailApp.sendEmail(CONFIG.adminEmail, "🚨 Invoice Pipeline Error", error.toString());
   }
 }
 // Batch Write to Sheets
 if (batchData.length > 0) {
   const lastRow = Math.max(sheet.getLastRow(), 1);
   sheet.getRange(lastRow + 1, 1, batchData.length, batchData[0].length).setValues(batchData);
 }
 // Mark all processed threads as read so they aren't parsed again
 processedThreads.forEach(t => t.markRead());
}

Na koniec skrypt wywołuje thread.markRead() na każdym przetworzonym e‑mailu. Dzięki temu przy następnym uruchomieniu skrypt całkowicie je zignoruje i zajmie się tylko nowymi.

5. Funkcja pomocnicza Gemini API (tryb JSON)

Podczas wywoływania LLM‑ów programiści często stosują inżynierię promptów typu „Zwróć blok JSON”. Jednak modele często odpowiadają gadatliwymi wstępami (np. „Jasne, oto twoje dane: [JSON]”), co powoduje awarie parserów w dalszej części procesu.

Ustawiając responseMimeType: "application/json" i przekazując rygorystyczny responseSchema, wymuszamy, by Gemini REST API odpowiedziało wyłącznie gwarantowanym obiektem JSON zawierającym dokładnie nasze nagłówki kolumn arkusza.

function callGeminiAPI(apiKey, partsArray) {
 const url = https://generativelanguage.googleapis.com/v1beta/models/${CONFIG.model}:generateContent?key=${apiKey};
  const responseSchema = {
   type: "OBJECT",
   properties: {
     vendor: { type: "STRING" },
     invoiceNumber: { type: "STRING" },
     totalAmount: { type: "NUMBER" },
     currency: { type: "STRING" },
     itemsSummary: { type: "STRING" }
   },
   required: ["vendor", "totalAmount"]
 };
  const payload = {
   contents: [{ parts: partsArray }],
   generationConfig: {
     responseMimeType: "application/json",
     responseSchema: responseSchema
   }
 };
  const options = {
   method: "POST",
   contentType: "application/json",
   payload: JSON.stringify(payload),
   muteHttpExceptions: true
 };
  const response = UrlFetchApp.fetch(url, options);
 const jsonResponse = JSON.parse(response.getContentText());
  return JSON.parse(jsonResponse.candidates[0].content.parts[0].text);
}

Krok 3: Zautomatyzuj pipeline Google Apps Script

Kod ma wartość tylko wtedy, gdy ułatwia ci życie. 

Google Apps Script oferuje potężne środowiska wykonywania — od interaktywnych przycisków dla użytkownika po całkowicie bezgłowe zadania w tle w stylu cron.

Metoda 1: Wyzwalanie przez interfejs arkusza

Jeśli tworzysz to narzędzie dla nietechnicznego zespołu księgowego, prawdopodobnie nie będą chcieli otwierać edytora Apps Script tylko po to, by przetworzyć dzisiejsze faktury. 

Ponieważ uwzględniliśmy funkcję onOpen() w naszym kodzie, Apps Script automatycznie dodaje niestandardowe menu bezpośrednio do interfejsu Arkuszy Google za każdym razem, gdy arkusz jest otwierany.

1. Wróć do Arkusza Google i odśwież stronę.
2. Odczekaj kilka sekund i spójrz na górny pasek menu. Zobaczysz nowe menu rozwijane o nazwie 🤖 AI Automations.
3. Kliknij je i wybierz Fetch New Invoices.

4. Przy pierwszym uruchomieniu Google poprosi cię o autoryzację skryptu (aby czytał twoją pocztę Gmail i wysyłał e‑maile w twoim imieniu). Po autoryzacji skrypt wykona się w czasie rzeczywistym. Możesz obserwować, jak wyodrębnione dane JSON wypełniają wiersze na twoich oczach!

Metoda 2: Automatyzacja bezgłowa przez wyzwalacze czasowe

Jeśli chcesz prawdziwej automatyzacji ustaw i zapomnij, możesz użyć natywnych wyzwalaczy Time‑Driven, aby pipeline działał autonomicznie w tle.

1. W edytorze Apps Script kliknij Wyzwalacze (ikona zegara) na lewym pasku bocznym.

2. Kliknij Add Trigger w prawym dolnym rogu.

3. Ustaw funkcję na processInvoices.
4. Zmień źródło zdarzenia na Time‑driven i ustaw uruchamianie co godzinę (np. co 6 godzin).
5. Kliknij Zapisz.

Twój bezgłowy, AI‑owy pipeline działa teraz w pełni autonomicznie.

Nawet jeśli twój komputer jest całkowicie wyłączony, serwery Google co sześć godzin się „obudzą”, przeskanują twoją skrzynkę, przetworzą faktury przez Gemini, zapiszą dane w Arkuszach i wrócą do uśpienia. 

Możesz monitorować sukces lub niepowodzenie tych wykonań w tle, klikając kartę Executions w edytorze Apps Script, aby zobaczyć logi.

Krok 4: Testowanie wyodrębniania danych przez AI

Skoro kod jest gotowy, musimy go przetestować, aby upewnić się, że pipeline ekstrakcji działa zgodnie z oczekiwaniami.

Przyjrzymy się dwóm praktycznym scenariuszom, aby zobaczyć, jak Gemini API radzi sobie z różnymi formatami danych i jak wyglądają faktyczne odpowiedzi.

Test 1: Wyodrębnianie z e‑maila w czystym tekście

Najpierw przetestujemy fakturę osadzoną bezpośrednio w treści e‑maila.

1. Wyślij sobie e‑mail z tematem „Invoice INV-2023-88493”.
2. W treści wpisz niestrukturyzowany tekst, np.: „Hej zespole, zapłaćcie proszę Acme Corp 450,00 USD za licencję oprogramowania za Q3.”
3. Nadaj wiadomości etykietę invoices i upewnij się, że pozostaje nieprzeczytana.

4. Uruchom skrypt z niestandardowego menu.

Za kulisami Gemini otrzymuje ten niestrukturyzowany tekst i ściśle trzyma się naszego schematu JSON. 

Zamiast odpowiadać wstępem konwersacyjnym, zwraca surowy ładunek. 

Ponieważ odpowiedź to idealnie ustrukturyzowany JSON, nasza tablica batchData.push() bezproblemowo odczytuje extractedData.totalAmount i loguje 6550 prosto do Arkusza Google, bez potrzeby złożonej logiki Regex.

Test 2: Wyodrębnianie z załącznika PDF

Następnie przetestujmy prawdziwą moc Gemini 2.5 Flash, przekazując mu dokument PDF.

1. Wygeneruj lub pobierz przykładową fakturę PDF (np. na 20 700,00 USD od ProTech Cloud Services).
2. Wyślij sobie dokument PDF. Treść e‑maila może pozostać całkiem pusta!
3. Nadaj etykietę invoices i oznacz jako nieprzeczytane.

4. Uruchom skrypt. Pipeline wykryje załącznik, przekonwertuje go do Base64, a Gemini wizualnie odczyta dokument, aby wyodrębnić dostawcę i kwotę całkowitą.

Tutaj architektura pokazuje swoją wartość. 

Nie musiałeś pisać własnego OCR (optycznego rozpoznawania znaków), zarządzać osobną biblioteką do parsowania PDF ani tworzyć wyrażeń regularnych do wyszukania kwoty całkowitej. 

LLM natywnie obsłużył niestrukturyzowane dane wizualne.

Podsumowanie

Automatyzacja procesów biznesowych nie wymaga zarządzania ciężką infrastrukturą ani walki ze złożonymi pętlami autoryzacyjnymi. 

Łącząc Google Apps Script z Gemini API, zbudowaliśmy inteligentny, bezserwerowy pipeline danych, który działa całkowicie w chmurowym ekosystemie, którego używasz na co dzień.

Siła tej architektury tkwi w prostocie. Zamiast przygotowywać serwery, konfigurować webhooki czy zarządzać bezpiecznymi plikami z poświadczeniami na zewnętrznym serwerze, Apps Script natywnie obsługuje kontekst, uwierzytelnianie i wykonanie. 

Tymczasem Gemini eliminuje potrzebę kruchych wyrażeń regularnych czy drogiego oprogramowania OCR, zamieniając chaotyczne treści e‑maili i niestrukturyzowane PDF‑y w przewidywalne wiersze bazy danych za pomocą jednego wywołania API.

Aby pójść dalej i odkryć, co jeszcze możesz zbudować z programistycznym dostępem do LLM‑ów, polecam sprawdzić kurs DataCamp Introduction to APIs in Python albo zagłębić się w projektowanie inteligentnych przepływów pracy na AI Agent Fundamentals .