Google Apps Script ve Gemini API Eğitimi: Akıllı Veri Çıkarma

Manuel veri girişi, verimliliğin en büyük düşmanıdır. Ekibiniz faturalar, rezervasyon onayları veya müşteri geri bildirim formları gibi operasyonel e-postalardan veri çıkarmaya dayanıyorsa, geleneksel ayrıştırma yöntemlerinin kabusuna muhtemelen aşinasınızdır. 

Geçmişte geliştiriciler, fatura numaraları veya tahakkuk tutarları gibi ayrıntıları çıkarmak için Düzenli İfadeler’e (Regex) güvenirdi. Ancak Regex son derece kırılgandır; bir tedarikçi e-posta şablonunu değiştirdiğinde veya rastgele bir satır sonu eklediğinde, tüm ayrıştırıcı sessizce bozulur.

Bu eğitimde, Üretken Yapay Zeka kullanarak bu sorunu çözen, tamamen otomatik ve başsız bir veri hattını nasıl kuracağınızı göstereceğim. Okunmamış Gmail iletilerini okuyan, yapılandırılmamış metni akıllı çıkarım için Gemini API’ye ileten ve mükemmel biçimlendirilmiş JSON verisini doğrudan bir Google E-Tablosu’na kaydeden hafif bir betik yazacağız.

Önkoşullar:

• Bir Google hesabı
• JavaScript’e (Google Apps Script) temel düzeyde aşinalık
• Bir Gemini API anahtarı

Google Apps Script Nedir?

Google Apps Script, Google Dokümanlar, E-Tablolar, Sunular ve daha fazlası gibi Google Workspace uygulamalarını otomatikleştirmenize, özelleştirmenize ve genişletmenize olanak tanıyan, JavaScript tabanlı bulut tabanlı hızlı bir geliştirme platformudur. 

Platform doğrudan Google’ın sunucularında çalıştığı için yazılım kurmanıza, yerel ortamları yapılandırmanıza veya altyapı yönetmenize gerek yoktur. 

Apps Script, geliştiricilere/düşük kod geliştiricilerine Dokümanlar, E-Tablolar, Sunular, Drive ve daha fazlası gibi Google Workspace araçlarıyla programatik olarak etkileşim kurma olanağı sağlar. Özel menüler, düğme tıklamaları veya zamana dayalı zamanlayıcılar aracılığıyla otomasyonlar oluşturup çalıştırabilir veya bu hizmeti Google Workspace Marketplace için eklentiler geliştirmek ve yayınlamak amacıyla kullanabilirsiniz.

Google Apps Script nasıl çalışır

Google Apps Script, arka uç yapılandırması ve API kimlik doğrulamasının yükünü ortadan kaldırarak doğrudan mantık ve verilere odaklanmanıza olanak tanır. Bunu birkaç özellikle yapar:

• Bulut-Nativ Düzenleyici: JavaScript kodunuzu tamamen tarayıcınıza yerleşik web tabanlı bir IDE içinde yazarsınız, hata ayıklarsınız ve dağıtırsınız.
• Yerleşik Hizmetler: OAuth ve karmaşık API çağrılarıyla uğraşmak yerine, Google hizmetleriyle yerel olarak etkileşim kurmak için hazır küresel nesneleri (SpreadsheetApp, MailApp veya DriveApp gibi) kullanırsınız.
• Olay Tabanlı Tetikleyiciler: Betikler özel menü düğmeleriyle manuel olarak çalıştırılabilir veya zaman tabanlı tetikleyiciler (ör. her gece yarısı) ve olay tabanlı tetikleyiciler (ör. bir kullanıcı Google Form’u gönderdiğinde) kullanılarak otomatik çalışacak şekilde planlanabilir.

Google Apps Script Mimarisi: Gmail’den E-Tablolara Veri Hattı

Betiği yazmadan önce, verinin bu hat boyunca nasıl hareket ettiğini haritalayalım. Mimari, birlikte çalışan dört ayrı bileşene dayanır:

• Gmail (Kaynak): Süreç, standart arama operatörleri (örneğin is:unread label:invoices) kullanılarak gelen kutunuzun sorgulanmasıyla başlar. Betik, doğru e-posta dizilerini izole eder ve hem düz metin gövdeyi hem de ekli PDF dosyalarını çıkarır.
• Apps Script (Hesaplama): Düzenleme katmanı olarak görev yapar. Okunmamış diziler üzerinden yineleme yapar, ekleri base64 verisine dönüştürür ve hata raporlama ile toplu işleme mantığını yönetir.
• Gemini API (Dönüşüm Motoru): Apps Script, çok kipli bir yükü (e-posta metni artı PDF’ler) Gemini 2.5 Flash modeline gönderir. API çağrısında katı bir JSON yanıt şeması ileterek, modelin sohbet metni üretmesi yerine satıcı, toplam tutar ve para birimi gibi kesin değerleri çekmesini sağlarız.
• Google E-Tablolar (Hedef): Gemini yapılandırılmış JSON’u döndürdüğünde, Apps Script sonuçları ayrıştırır, tek bir diziye paketler ve verileri setValues() kullanarak etkin e-tablonuzun bir sonraki boş satırına toplu olarak ekler.

Neden bu kurulumda hesaplama katmanı olarak Google Apps Script’i kullanmalısınız? 

Birincil fayda, altyapı yükünün tamamen ortadan kaldırılmasıdır. Sunucu sağlama gereksinimi sıfırdır ve yalnızca e-postalarınızı okumak veya bir e-tabloya yazmak için Docker konteynerleri yapılandırmanız ya da karmaşık OAuth akışları kurmanız gerekmez. 

Apps Script, GmailApp ve SpreadsheetApp gibi hizmetlerle yerel olarak entegre olduğundan, kimlik doğrulamayı Google dahili olarak yönetir. Siz sadece kodu yazıp uç noktaları bağlarsınız.

Adım 1: Google Apps Script Ortamınızı Hazırlayın

Kod yazmadan önce, harici bağımlılıklarımızı hazırlamamız gerekiyor. Bu, Gemini API’ye erişimi güvence altına almayı, hedef e-tablomuzu oluşturmayı ve gelen faturaları düzgün şekilde etiketlemek için Gmail gelen kutumuzu yapılandırmayı içerir.

Gemini API Anahtarının Oluşturulması

Akıllı veri çıkarımımızı çalıştırmak için Gemini API’ye erişime ihtiyacımız var.

1. Şuraya gidin: Google AI Studio ve Google hesabınızla oturum açın.
2. Sol taraftaki gezinme menüsünde Get API key seçeneğine tıklayın.
3. Create API key düğmesine tıklayın. Bu anahtarı mevcut bir Google Cloud projesinde oluşturmayı seçebilir veya sizin için AI Studio’nun yeni bir proje oluşturmasına izin verebilirsiniz.
4. Oluşturulan dizeyi kopyalayın. 

Güvenlik En İyi Uygulaması: Bu anahtarı kaybetmeyin, ancak daha da önemlisi, kodunuzun içinde düz metin olarak gömmeyi planlamayın. Şimdilik pano veya güvenli bir not defterine kopyalı tutun; bir sonraki adımda Apps Script ortamımızda güvenli şekilde kilitleyeceğiz.

Google E-Tablosunu Hazırlama ve Anahtarı Güvenceye Alma

Çıkarılan verileri depolayacağımız bir yere ihtiyacımız var. Bu sayfa, otomasyon betiğimiz için de fırlatma rampası görevi görecek.

1. Veritabanı başlıklarını ayarlayın Yeni, boş bir Google E-Tablosu oluşturun. İlk satıra, betiğimizde tanımlayacağımız JSON şemasıyla eşleşecek şekilde şu sütun başlıklarını girin:

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

Verileriniz arttıkça başlıkların görünür kalması için üst satırı sabitleyin.

2. Apps Script’e erişin ve API Anahtarını kaydedin Artık Sayfa hazır olduğuna göre, Apps Script düzenleyicisini doğrudan buradan açabiliriz. Bu, kodumuzu otomatik olarak bu özel e-tabloya bağlar.

1. Google E-Tablonuzda üst menüden Extensions > Apps Script’e tıklayın.
2. Düzenleyici açıldığında sol kenar çubuğuna bakın ve Project Settings’i açmak için dişli simgesine tıklayın.

3. En alta kaydırarak Script Properties bölümünü bulun.
4. Add script property’e tıklayın.
5. Property alanına tam olarak GEMINI_API_KEY yazın.
6. Value alanına, az önce AI Studio’dan kopyaladığınız API anahtarını yapıştırın.
7. Save script properties’e tıklayın.

Daha sonra yazacağımız kod, kimlik bilgilerinizi ifşa etmeden bu değeri çalışma anında güvenli bir şekilde çekecek.

Adım 2: Google Apps Script Kodunu Yazın

Apps Script düzenleyicinizdeyken, varsayılan kodu silin. Otomasyon motorumuzu blok blok oluşturacağız.

1. Yapılandırma ve arayüz kurulumu

Küresel bir yapılandırma nesnesi tanımlayarak başlıyoruz. Bu, tüm sabit değişkenleri tek bir yerde toplayan temiz kod en iyi uygulamasıdır; böylece yalnızca bu üst bloğu düzenlemeniz yeterli olur.

Ayrıca bir onOpen() işlevi ekliyoruz. Bu yerleşik Apps Script tetikleyicisi, Google E-Tablonuzda özel bir menüyü otomatik olarak oluşturur; böylece teknik olmayan kullanıcılar kod düzenleyicisini hiç açmadan betiği elle çalıştırabilir.

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. Orkestrasyon kurulumu

processInvoices() işlevi ana orkestratör olarak görev yapar. Önce, daha önce ayarladığımız Betik Özellikleri’nden API anahtarınızı güvenli bir şekilde çeker. 

Ardından, gelen kutunuzu sorgulamak için yerleşik GmailApp hizmetini kullanır.

GmailApp.search(CONFIG.searchQuery) çağrısı yapılarak, betik is:unread label:invoices kuralımıza uyan bir dizi e-posta dizisini getirir. 

Eşleşmeler bulunursa, her diziyi dolaşır; en son iletiyi alır, düz metin gövdesini çıkarır ve ekli PDF dosyalarını izole eder.

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. E-postaları ve çok kipli PDF’leri işleme

E-posta dizilerinde döngü yaparken, en son iletiyi alıyoruz. Ancak faturalar nadiren düz metin olarak gelir; çoğunlukla PDF olarak eklenirler. 

Gemini 2.5 Flash’ın doğal olarak çok kipli olmasından yararlanarak, betiğimiz latestMessage.getAttachments() üzerinden döngü yapar, PDF’leri alır, Base64 dizesine dönüştürür ve bunları inlineData olarak doğrudan API yüküne iletir. 

Gemini PDF’yi görsel olarak “okur” ve verileri metin okuduğu kadar kolaylıkla çıkarır.

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. Toplu ekleme ve hata yönetimi

Performansı iyileştirmek için e-çizelgeye satır satır yazmıyoruz. 

Bunun yerine, çıkarılan JSON verilerini bir diziye (batchData) ekliyor ve en sonda setValues() kullanarak tek seferde yazıyoruz.

try...catch bloğuna dikkat edin. 

Gemini belirli bir e-postada halüsinasyon görür veya başarısız olursa, betik tamamen çökmez. Bunun yerine hatayı zarifçe yakalar ve MailApp.sendEmail() kullanarak yöneticiyi anında uyarır; bu da yüksek gözlemlenebilirlik sağlar.

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

Son olarak, betik işlenen her e-posta için thread.markRead() çağırır. Bu sayede betik bir sonraki çalıştığında bu e-postaları tamamen göz ardı eder ve yalnızca yenilerine bakar.

5. Gemini API yardımcı işlevi (JSON kipi)

LLM’leri çağırırken, geliştiriciler sıklıkla “Bir JSON bloğu döndür” gibi İstem Mühendisliği kullanır. Ancak modeller sıklıkla sohbet dolgu metinleriyle (ör. “Elbette, verileriniz burada: [JSON]”) yanıt verir; bu da aşağı akıştaki kod ayrıştırıcılarının çökmesine neden olur.

responseMimeType: "application/json" ayarını yapıp katı bir responseSchema sağladığımızda, Gemini REST API’sini yalnızca e-tablo sütun başlıklarımızı tam olarak içeren, garantili bir JSON nesnesi ile yanıt vermeye zorlarız.

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

Adım 3: Google Apps Script Veri Hattınızı Otomatikleştirin

Kod, hayatınızı kolaylaştırdığı sürece değerlidir. 

Google Apps Script, etkileşimli, kullanıcıya dönük düğmelerden tamamen başsız, arka plan cron görevlerine kadar güçlü yürütme ortamları sunar.

Yöntem 1: E-tablo arayüzü üzerinden tetikleme

Bu aracı teknik olmayan bir muhasebe ekibi için oluşturuyorsanız, bugünün faturalarını işlemek için muhtemelen Apps Script kod düzenleyicisini açmak istemeyeceklerdir. 

Koda onOpen() işlevini dahil ettiğimiz için, Apps Script her e-tablo açıldığında Google E-Tablolar arayüzüne otomatik olarak özel bir menü bağlar.

1. Google E-Tablonuza geri dönün ve sayfayı yenileyin.
2. Birkaç saniye bekleyin ve üst menü çubuğuna bakın. 🤖 AI Automations adlı yeni bir açılır menü göreceksiniz.
3. Tıklayın ve Fetch New Invoices’i seçin.

4. Bunu ilk kez çalıştırdığınızda, Google sizden betiği yetkilendirmenizi isteyecektir (Gmail’inizi okumak ve adınıza e-posta göndermek için). Yetkilendirdikten sonra betik gerçek zamanlı olarak çalışır. Çıkarılan JSON verisinin satırlara gözlerinizin önünde dolduğunu izleyebilirsiniz!

Yöntem 2: Zaman tetikleyicileriyle başsız otomasyon

Gerçek bir kur ve unut otomasyonu istiyorsanız, yerel Zaman Tabanlı Tetikleyicileri kullanarak veri hattını arka planda özerk biçimde çalıştırabilirsiniz.

1. Apps Script düzenleyicisinde, sol kenar çubuğundaki Tetikleyiciler (Saat Simgesi) seçeneğine tıklayın.

2. Sağ alt köşedeki Add Trigger’a tıklayın.

3. İşlevi processInvoices olarak ayarlayın.
4. Olay kaynağını Time-driven olarak değiştirin ve Saat zamanlayıcısında (ör. her 6 saatte bir) çalışacak şekilde ayarlayın.
5. Kaydet’e tıklayın.

Başsız yapay zeka veri hattınız artık tamamen özerk.

Bilgisayarınız tamamen kapalı olsa bile, Google’ın sunucuları her altı saatte bir uyanacak, gelen kutunuzu tarayacak, faturaları Gemini ile ayrıştıracak, verileri E-Tablolar’a kaydedecek ve tekrar uykuya geçecek. 

Bu arka plan yürütmelerinin başarı ya da başarısızlığını, Apps Script düzenleyicisindeki Yürütmeler sekmesine tıklayarak günlükleri görüntüleyip izleyebilirsiniz.

Adım 4: Yapay Zeka ile Veri Çıkarımını Test Etme

Artık kod yerinde olduğuna göre, çıkarım hattının beklendiği gibi çalıştığından emin olmak için test etmemiz gerekiyor.

Gemini API’nin farklı veri biçimlerini nasıl ele aldığını ve gerçek yanıtların nasıl göründüğünü görmek için iki pratik senaryoya bakalım.

Test 1: Düz metin e-postadan çıkarım

Önce, doğrudan e-posta gövdesine gömülü bir faturayı test edeceğiz.

1. Kendinize şu konu satırıyla bir e-posta gönderin: "Invoice INV-2023-88493".
2. Gövdeye şu gibi yapılandırılmamış bir metin yazın: "Merhaba Ekip, lütfen Q3 yazılım lisansı için Acme Corp’a 450,00 $ USD ödeyin."
3. E-postaya invoices etiketini uygulayın ve okunmamış durumda kaldığından emin olun.

4. Betik’i özel menü üzerinden çalıştırın.

Arka planda, Gemini bu yapılandırılmamış metni alır ve JSON şemamıza sıkı sıkıya uyar. 

Sohbet dolgu metniyle yanıtlamak yerine ham bir yük döndürür. 

Yanıt mükemmel şekilde yapılandırılmış JSON olduğu için, batchData.push() dizimiz extractedData.totalAmount değerini sorunsuzca okur ve 6550 değerini, karmaşık Regex mantığı gerektirmeden doğrudan Google E-Tablosu’na kaydeder.

Test 2: PDF ekinden çıkarım

Şimdi de bir PDF belgesini ileterek Gemini 2.5 Flash’ın gerçek gücünü test edelim.

1. Örnek bir PDF fatura oluşturun veya indirin (ör. ProTech Cloud Services’tan 20.700,00 $).
2. PDF belgesini kendinize e-posta ile gönderin. E-posta gövdesini tamamen boş bırakabilirsiniz!
3. invoices etiketini uygulayın ve okunmamış olarak işaretleyin.

4. Betik’i çalıştırın. Veri hattı eki algılayacak, Base64’e dönüştürecek ve Gemini belgeyi görsel olarak okuyarak satıcıyı ve toplam tutarı çıkaracaktır.

İşte mimarinin değerini kanıtladığı yer. 

Özel bir OCR (Optik Karakter Tanıma) mantığı yazmanıza, ayrı bir PDF ayrıştırma kitaplığı yönetmenize veya toplam tutarı bulmak için düzenli ifadeler yazmanıza gerek kalmadı. 

LLM, yapılandırılmamış görsel veriyi yerel olarak ele aldı.

Sonuç

İş akışlarını otomatikleştirmek, ağır altyapı yönetmeyi veya karmaşık yetkilendirme döngüleriyle mücadele etmeyi gerektirmez. 

Google Apps Script’i Gemini API ile eşleştirerek, her gün zaten kullandığınız bulut ekosistemi içinde tamamen çalışan, akıllı ve sunucusuz bir veri hattı oluşturduk.

Bu mimarinin gücü sadeliğinde yatar. Sunucu sağlamak, web kancaları yapılandırmak veya harici bir sunucuda güvenli kimlik bilgisi dosyalarını yönetmek yerine, Apps Script bağlamı, kimlik doğrulamayı ve yürütmeyi yerel olarak ele alır. 

Bu arada Gemini, kırılgan düzenli ifadelere veya pahalı OCR yazılımlarına olan ihtiyacı ortadan kaldırarak, dağınık e-posta gövdelerini ve yapılandırılmamış PDF’leri tek bir API çağrısıyla öngörülebilir veritabanı satırlarına dönüştürür.

Becerilerinizi daha da geliştirmek ve LLM’lere programatik erişimle başka neler inşa edebileceğinizi keşfetmek için DataCamp’in Python’da API’lere Giriş kursuna göz atmanızı veya Yapay Zekâ Aracısı Temelleri kursuyla akıllı iş akışları tasarımına derinlemesine dalmanızı öneririm.