Tutorial Google Apps Script dan Gemini API: Ekstraksi Data Cerdas

Entri data manual adalah musuh produktivitas. Jika tim Anda bergantung pada ekstraksi data dari email operasional seperti faktur, konfirmasi pemesanan, atau formulir umpan balik pelanggan, Anda mungkin akrab dengan mimpi buruk metode parsing tradisional. 

Secara historis, developer mengandalkan Regular Expressions (Regex) untuk mengekstrak detail seperti nomor faktur atau jumlah penagihan. Namun Regex sangat rapuh; begitu vendor mengubah templat email mereka atau menambahkan jeda baris acak, seluruh parser diam-diam rusak.

Dalam tutorial ini, saya akan menunjukkan cara membangun pipeline tanpa antarmuka yang sepenuhnya otomatis untuk menyelesaikan masalah ini menggunakan Generative AI. Kita akan menulis skrip ringan yang membaca pesan Gmail yang belum dibaca, mengirimkan teks tidak terstruktur ke Gemini API untuk ekstraksi cerdas, dan mencatat data JSON yang terstruktur rapi langsung ke Google Sheet.

Prasyarat:

• Akun Google
• Pemahaman dasar JavaScript (Google Apps Script)
• Kunci API Gemini

Apa itu Google Apps Script?

Google Apps Script adalah platform pengembangan aplikasi cepat berbasis JavaScript di cloud yang memungkinkan Anda mengotomatiskan, menyesuaikan, dan memperluas aplikasi Google Workspace seperti Google Docs, Sheets, Slides, dan lainnya. 

Karena platform ini berjalan langsung di server Google, tidak perlu memasang perangkat lunak, mengonfigurasi lingkungan lokal, atau mengelola infrastruktur. 

Apps Script memberi kemampuan bagi developer/pengembang low-code untuk berinteraksi secara terprogram dengan alat Google Workspace seperti Docs, Sheets, Slides, Drive, dan lainnya. Anda dapat membangun dan menjalankan otomatisasi melalui menu khusus, klik tombol, atau jadwal berbasis waktu, atau menggunakan layanan ini untuk membangun dan memublikasikan add-on ke Google Workspace Marketplace.

Cara kerja Google Apps Script

Google Apps Script menyederhanakan konfigurasi backend dan autentikasi API, sehingga Anda dapat langsung fokus pada logika dan data. Ini dilakukan melalui beberapa fitur:

• Editor Cloud-Native: Anda menulis, melakukan debug, dan melakukan deploy kode JavaScript sepenuhnya di IDE berbasis web langsung di browser Anda.
• Layanan Bawaan: Alih-alih bergulat dengan OAuth dan panggilan API yang kompleks, Anda menggunakan objek global siap pakai (seperti SpreadsheetApp, MailApp, atau DriveApp) untuk berinteraksi secara native dengan layanan Google.
• Pemicu Berbasis Peristiwa: Skrip dapat dijalankan secara manual melalui tombol menu khusus, atau dijadwalkan berjalan otomatis menggunakan pemicu berbasis waktu (mis., setiap tengah malam) dan pemicu berbasis peristiwa (mis., saat pengguna mengirim Google Form).

Arsitektur Google Apps Script: Pipeline Gmail ke Sheets

Sebelum menulis skrip, mari kita petakan bagaimana data bergerak melalui pipeline ini. Arsitektur ini bergantung pada empat komponen berbeda yang bekerja bersama:

• Gmail (Sumber): Proses dimulai dengan menelusuri kotak masuk Anda menggunakan operator pencarian standar (seperti is:unread label:invoices). Skrip mengisolasi thread email yang benar dan mengekstrak badan teks biasa serta semua file PDF terlampir.
• Apps Script (Komputasi): Bertindak sebagai lapisan orkestrasi. Ia melakukan iterasi pada thread yang belum dibaca, memformat lampiran menjadi data base64, dan menangani logika pelaporan error serta pemrosesan batch.
• Gemini API (Mesin Transformasi): Apps Script mengirimkan payload multimodal (teks email plus PDF) ke model Gemini 2.5 Flash. Dengan menyertakan skema respons JSON yang ketat dalam panggilan API, kita memaksa model untuk mengambil nilai tepat seperti vendor, total jumlah, dan mata uang, alih-alih menghasilkan teks percakapan.
• Google Sheets (Tujuan): Setelah Gemini mengembalikan JSON terstruktur, Apps Script mengurai hasilnya, mengemasnya menjadi satu array, dan memasukkan data secara batch ke baris kosong berikutnya di spreadsheet aktif Anda menggunakan setValues().

Mengapa menggunakan Google Apps Script sebagai lapisan komputasi untuk build ini? 

Manfaat utamanya adalah penghapusan total beban infrastruktur. Tidak ada penyediaan server yang diperlukan, dan Anda tidak perlu mengonfigurasi kontainer Docker atau menyiapkan alur OAuth yang rumit hanya untuk membaca email atau menulis ke spreadsheet. 

Karena Apps Script terintegrasi secara native dengan layanan seperti GmailApp dan SpreadsheetApp, Google menangani autentikasi secara internal. Anda cukup menulis kode dan menyambungkan endpoint.

Langkah 1: Siapkan Lingkungan Google Apps Script Anda

Sebelum kita menulis kode, kita perlu menyiapkan dependensi eksternal. Ini mencakup mengamankan akses ke Gemini API, membuat spreadsheet tujuan, dan mengonfigurasi kotak masuk Gmail agar menandai faktur yang masuk dengan benar.

Membuat Kunci API Gemini

Untuk mendukung ekstraksi data cerdas, kita memerlukan akses ke Gemini API.

1. Buka Google AI Studio dan masuk dengan akun Google Anda.
2. Di menu navigasi kiri, klik Get API key.
3. Klik tombol Create API key. Anda dapat memilih membuat kunci ini di proyek Google Cloud yang sudah ada atau membiarkan AI Studio membuat yang baru untuk Anda.
4. Salin string yang dihasilkan. 

Praktik Keamanan Terbaik: Jangan sampai kehilangan kunci ini, dan yang lebih penting, jangan berencana menuliskannya secara hardcode dalam teks biasa di dalam kode Anda. Simpan sementara di clipboard atau notepad yang aman; kita akan menguncinya secara aman di lingkungan Apps Script pada langkah berikutnya.

Menyiapkan Google Sheet dan Mengamankan Kunci

Kita memerlukan tempat untuk menyimpan data yang diekstrak. Sheet ini juga akan bertindak sebagai landasan peluncuran untuk skrip otomatisasi kita.

1. Atur header basis data Buat Google Sheet kosong baru. Di baris pertama, buat header kolom berikut untuk menyesuaikan skema JSON yang akan kita definisikan di skrip:

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

Bekukan baris teratas agar header tetap terlihat saat data Anda bertambah.

2. Akses Apps Script dan simpan API Key Sekarang Sheet sudah ada, kita dapat membuka editor Apps Script langsung darinya. Ini otomatis menghubungkan kode kita ke spreadsheet spesifik ini.

1. Di Google Sheet Anda, klik Extensions > Apps Script dari menu atas.
2. Setelah editor terbuka, lihat bilah sisi kiri dan klik ikon roda gigi untuk membuka Project Settings.

3. Gulir ke bagian bawah untuk menemukan bagian Script Properties.
4. Klik Add script property.
5. Pada kolom Property, ketik persis GEMINI_API_KEY.
6. Pada kolom Value, tempel API key yang Anda salin dari AI Studio sebelumnya.
7. Klik Save script properties.

Kode yang kita tulis nanti sekarang akan mengambil nilai ini secara aman saat runtime tanpa mengekspos kredensial Anda.

Langkah 2: Tulis Kode Google Apps Script

Saat Anda berada di editor Apps Script, silakan hapus kode default apa pun. Kita akan membangun mesin otomatisasi kita blok demi blok.

1. Penyiapan konfigurasi dan UI

Kita mulai dengan mendefinisikan objek konfigurasi global. Ini adalah praktik terbaik clean code yang mengelompokkan semua variabel hardcode di satu tempat, sehingga Anda hanya perlu mengedit blok paling atas ini.

Kita juga menambahkan fungsi onOpen(). Pemicu bawaan Apps Script ini otomatis membuat menu khusus di Google Sheet Anda, memungkinkan pengguna non-teknis menjalankan skrip secara manual tanpa perlu membuka editor kode.

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. Penyiapan orkestrasi

Fungsi processInvoices() bertindak sebagai orkestra utama. Ini dimulai dengan menarik API key Anda secara aman dari Script Properties yang kita atur sebelumnya. 

Kemudian, ia menggunakan layanan bawaan GmailApp untuk menelusuri kotak masuk Anda.

Dengan memanggil GmailApp.search(CONFIG.searchQuery), skrip mengambil array thread email yang cocok dengan aturan is:unread label:invoices kita. 

Jika menemukan kecocokan, skrip melakukan loop pada setiap thread, mengambil pesan terbaru, mengekstrak badan teks biasa, dan mengisolasi semua file PDF terlampir.

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. Memproses email dan PDF multimodal

Saat kita melakukan loop pada thread email, kita mengambil pesan terbaru. Namun, faktur jarang datang sebagai teks polos; hampir selalu dilampirkan sebagai PDF. 

Dengan memanfaatkan Gemini 2.5 Flash yang secara native multimodal, skrip kita melakukan loop pada latestMessage.getAttachments(), mengambil PDF apa pun, mengonversinya menjadi string Base64, dan mengirimkannya langsung ke payload API sebagai inlineData. 

Gemini "membaca" PDF secara visual dan mengekstrak data semudah membaca teks.

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. Penyisipan batch dan penanganan error

Untuk mengoptimalkan performa, kita tidak menulis ke spreadsheet satu per satu baris. 

Sebagai gantinya, kita mendorong data JSON yang diekstrak ke dalam array (batchData) dan menuliskannya sekaligus di akhir menggunakan setValues().

Perhatikan blok try...catch. 

Jika Gemini berhalusinasi atau gagal pada email tertentu, skrip tidak langsung crash. Sebaliknya, ia menangkap error dengan baik dan menggunakan MailApp.sendEmail() untuk segera memberi tahu administrator, memastikan tingkat observabilitas tinggi.

 // 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());
}

Terakhir, skrip memanggil thread.markRead() pada setiap email yang diproses. Ini memastikan bahwa saat skrip berjalan lagi, email tersebut diabaikan sepenuhnya dan hanya mencari yang baru.

5. Fungsi pembantu Gemini API (mode JSON)

Saat memanggil LLM, developer sering menggunakan Prompt Engineering seperti "Kembalikan blok JSON". Namun, model sering menjawab dengan pembuka percakapan (mis. "Tentu, berikut datanya: [JSON]"), yang menyebabkan parser kode di hilir gagal.

Dengan menyetel responseMimeType: "application/json" dan menyediakan responseSchema yang ketat, kita memaksa Gemini REST API untuk membalas hanya dengan objek JSON yang terjamin berisi header kolom spreadsheet kita secara tepat.

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);
}

Langkah 3: Otomatiskan Pipeline Google Apps Script Anda

Kode hanya bernilai jika memudahkan hidup Anda. 

Google Apps Script menyediakan lingkungan eksekusi yang kuat mulai dari tombol interaktif yang berhadapan dengan pengguna hingga cron job latar belakang yang sepenuhnya tanpa antarmuka.

Metode 1: Memicu melalui UI spreadsheet

Jika Anda membangun alat ini untuk tim akuntansi non-teknis, mereka mungkin tidak ingin membuka editor kode Apps Script hanya untuk memproses faktur hari ini. 

Karena kita menyertakan fungsi onOpen() dalam kode, Apps Script secara otomatis menautkan menu khusus langsung ke antarmuka Google Sheets setiap kali spreadsheet dibuka.

1. Kembali ke Google Sheet Anda dan segarkan halaman.
2. Tunggu beberapa detik, lalu lihat bilah menu atas. Anda akan melihat dropdown baru bernama 🤖 AI Automations.
3. Klik dan pilih Fetch New Invoices.

4. Pertama kali Anda menjalankannya, Google akan meminta Anda mengotorisasi skrip (untuk membaca Gmail Anda dan mengirim email atas nama Anda). Setelah diotorisasi, skrip akan berjalan secara real-time. Anda dapat melihat data JSON yang diekstrak mengisi baris di depan mata Anda!

Metode 2: Otomatisasi tanpa antarmuka melalui pemicu berbasis waktu

Jika Anda menginginkan otomasi sejati set and forget, Anda dapat menggunakan Time-Driven Triggers native untuk menjalankan pipeline secara otonom di latar belakang.

1. Di editor Apps Script, klik Triggers (ikon jam) di bilah sisi kiri.

2. Klik Add Trigger di pojok kanan bawah.

3. Setel fungsi ke processInvoices.
4. Ubah sumber peristiwa menjadi Time-driven dan atur untuk berjalan dengan pengatur waktu Jam (mis., setiap 6 jam).
5. Klik Save.

Pipeline AI tanpa antarmuka Anda kini sepenuhnya otonom.

Bahkan jika komputer Anda benar-benar dimatikan, server Google akan aktif setiap enam jam, memindai kotak masuk Anda, mem-parse faktur melalui Gemini, mencatat data ke Sheets, lalu kembali siaga. 

Anda dapat memantau keberhasilan atau kegagalan eksekusi latar belakang ini dengan mengeklik tab Executions di editor Apps Script untuk melihat log.

Langkah 4: Menguji Ekstraksi Data AI

Kini kode sudah siap, kita perlu mengujinya untuk memastikan pipeline ekstraksi berfungsi sebagaimana mestinya.

Mari lihat dua skenario praktis untuk melihat bagaimana Gemini API menangani format data yang berbeda dan seperti apa respons sebenarnya.

Uji 1: Ekstraksi email teks polos

Pertama, kita akan menguji faktur yang disematkan langsung di badan email.

1. Kirimkan email ke diri Anda sendiri dengan subjek "Invoice INV-2023-88493".
2. Di badan email, tuliskan teks tidak terstruktur seperti: "Hi Team, please pay Acme Corp $450.00 USD for the Q3 software license."
3. Terapkan label invoices pada email dan pastikan tetap belum dibaca.

4. Jalankan skrip melalui menu khusus.

Di balik layar, Gemini menerima teks tidak terstruktur ini dan secara ketat mematuhi skema JSON kita. 

Alih-alih membalas dengan padding percakapan, ia mengembalikan payload mentah. 

Karena respons berupa JSON yang terstruktur sempurna, array batchData.push() kita dengan mulus membaca extractedData.totalAmount dan mencatat 6550 langsung ke Google Sheet tanpa memerlukan logika Regex yang kompleks.

Uji 2: Ekstraksi dari lampiran PDF

Selanjutnya, mari uji kekuatan sejati Gemini 2.5 Flash dengan memberinya dokumen PDF.

1. Buat atau unduh contoh faktur PDF (mis., sebesar $20.700,00 dari ProTech Cloud Services).
2. Kirimkan email ke diri Anda sendiri dengan melampirkan PDF tersebut. Anda dapat membiarkan badan email benar-benar kosong!
3. Terapkan label invoices dan tandai sebagai belum dibaca.

4. Jalankan skrip. Pipeline akan mendeteksi lampiran, mengonversinya ke Base64, dan Gemini akan membaca dokumen secara visual untuk mengekstrak vendor dan total jumlah.

Di sinilah arsitektur ini membuktikan nilainya. 

Anda tidak perlu menulis logika OCR (Optical Character Recognition) khusus, mengelola pustaka parsing PDF terpisah, atau menulis regular expression untuk menemukan total jumlah. 

LLM menangani data visual tidak terstruktur secara native.

Kesimpulan

Mengotomatiskan alur kerja bisnis tidak memerlukan pengelolaan infrastruktur berat atau berjuang dengan loop otorisasi yang kompleks. 

Dengan memasangkan Google Apps Script dengan Gemini API, kita membangun pipeline data cerdas tanpa server yang berjalan sepenuhnya dalam ekosistem cloud yang sudah Anda gunakan setiap hari.

Kekuatan arsitektur ini terletak pada kesederhanaannya. Alih-alih menyediakan server, mengonfigurasi webhook, atau mengelola file kredensial aman di server eksternal, Apps Script menangani konteks, autentikasi, dan eksekusi secara native. 

Sementara itu, Gemini menghilangkan kebutuhan akan regular expression yang rapuh atau perangkat lunak OCR yang mahal, mengubah badan email yang berantakan dan PDF tidak terstruktur menjadi baris basis data yang dapat diprediksi hanya dengan satu panggilan API.

Untuk meningkatkan keterampilan Anda dan mengeksplorasi hal lain yang dapat Anda bangun dengan akses terprogram ke LLM, saya sarankan melihat Introduction to APIs in Python dari DataCamp atau mendalami perancangan alur kerja cerdas melalui AI Agent Fundamentals course.