Apps Script ile Vertex AI Entegrasyonu: Yapay Zeka Gücünü Uygulamalarınıza Taşıyın

Apps Script ile Vertex AI Entegrasyonu: Yapay Zeka Gücünü Uygulamalarınıza Taşıyın

Google Apps Script ve Google Cloud Vertex AI, bulut tabanlı uygulamalarınızı akıllı yeteneklerle donatmak için güçlü bir ikili oluşturur. Bu makale, Apps Script projelerinizi Vertex AI’ın sunduğu gelişmiş yapay zeka modelleriyle nasıl entegre edeceğinizi adım adım açıklayarak, otomasyon ve zeka katmanını uygulamalarınıza taşımanız için kapsamlı bir rehber sunmaktadır. Hazırlık aşamalarından kod örneklerine kadar tüm detayları burada bulacaksınız.

Apps Script ve Vertex AI Nedir?

Google’ın iki güçlü platformu olan Apps Script ve Vertex AI, modern uygulama geliştirme süreçlerinde önemli roller oynar. Bu bölümde, her bir platformu yakından tanıyacak ve entegrasyonlarının temel mantığını kavrayacağız.

Google Apps Script’e Yakından Bakış

Google Apps Script (GAS), Google Workspace (eski adıyla G Suite) ürünlerini otomatikleştirmek, genişletmek ve birbirine bağlamak için JavaScript tabanlı bir bulut komut dosyası platformudur. Google Sheets, Docs, Gmail, Calendar gibi uygulamalarla doğrudan etkileşim kurabilir, harici API’lara bağlanabilir ve özel web uygulamaları oluşturabilirsiniz. Sunucusuz yapısı sayesinde altyapı yönetimiyle uğraşmadan hızlıca çözümler geliştirmenizi sağlar.

Google Cloud Vertex AI’a Giriş

Google Cloud Vertex AI, makine öğrenimi (ML) modellerini oluşturmak, eğitmek, dağıtmak ve yönetmek için birleşik bir platformdur. Veri bilimcileri ve ML mühendisleri için uçtan uca bir çözüm sunar. Generative AI Studio gibi araçlarıyla büyük dil modelleri (LLM’ler) ve diğer üretken yapay zeka modellerine kolay erişim sağlar. Metin oluşturma, özetleme, görsel tanıma, tahminleme gibi birçok farklı yapay zeka yeteneğini barındırır.

Entegrasyonun Temelleri

Apps Script, bir istemci görevi görerek Vertex AI’ın REST API’larına HTTP istekleri gönderir. Bu entegrasyon, Apps Script’in basitliği ve Google Workspace entegrasyonu ile Vertex AI’ın gelişmiş yapay zeka gücünü birleştirir. Örneğin, bir Google E-Tablosu’ndaki verileri kullanarak Vertex AI’dan tahminler alabilir, gelen e-postaları yapay zeka ile özetleyebilir veya bir Google Dokümanı’nda metin oluşturabilirsiniz. Temelinde, Apps Script’in UrlFetchApp servisi ve doğru kimlik doğrulama mekanizmaları yatar.

Neden Apps Script ile Vertex AI Kullanmalıyız?

Apps Script ve Vertex AI entegrasyonu, iş akışlarınızı dönüştürmek ve uygulamalarınıza akıllı yetenekler kazandırmak için birçok avantaj sunar.

Verimlilik ve Otomasyon

Yapay zeka destekli otomasyon, tekrarlayan görevleri ortadan kaldırarak verimliliği artırır. Apps Script ile Vertex AI’ı birleştirerek, veri girişi, raporlama, içerik oluşturma ve daha fazlası gibi süreçleri otomatik hale getirebilirsiniz. Örneğin, bir e-tablodaki müşteri geri bildirimlerini otomatik olarak analiz edip duygu analizi yapabilir veya gelen e-postaları özetleyip ilgili departmanlara yönlendirebilirsiniz.

Gelişmiş Yapay Zeka Yetenekleri

Vertex AI, Google’ın en yeni ve güçlü yapay zeka modellerine (örneğin Gemini, PaLM) erişim sağlar. Bu modelleri Apps Script aracılığıyla kullanarak uygulamalarınıza metin oluşturma, çeviri, özetleme, görsel analiz, veri tahmini gibi gelişmiş yetenekler kazandırabilirsiniz. Kendi özel modellerinizi eğitmenize gerek kalmadan, önceden eğitilmiş modellerin gücünden faydalanabilirsiniz.

Maliyet Etkinliği ve Ölçeklenebilirlik

Hem Apps Script hem de Vertex AI, kullandıkça öde (pay-as-you-go) modeline dayanır. Bu, yalnızca kullandığınız kaynaklar için ödeme yapacağınız anlamına gelir, bu da maliyet etkinliği sağlar. Ayrıca, her iki platform da sunucusuz yapıda olduğu için altyapı yönetimi veya ölçeklendirme konusunda endişelenmenize gerek kalmaz; Google tüm bu yükü sizin için üstlenir.

Google Workspace Ekosistemi ile Kusursuz Entegrasyon

Apps Script’in en büyük avantajlarından biri, Google Workspace uygulamalarıyla derin entegrasyonudur. Bu sayede, Sheets, Docs, Gmail, Drive veya Calendar gibi uygulamalardaki verileri doğrudan Vertex AI modellerine besleyebilir ve sonuçları yine bu uygulamalar içinde kullanabilirsiniz. Bu kusursuz entegrasyon, kullanıcı dostu ve güçlü çözümler geliştirmenizi kolaylaştırır.

Gerekli Ön Hazırlıklar ve Google Cloud Projesi Kurulumu

Apps Script’ten Vertex AI’a erişebilmek için öncelikle bir Google Cloud projesi oluşturmanız ve gerekli API’leri etkinleştirmeniz gerekir.

Google Cloud Projesi Oluşturma

Eğer bir Google Cloud projeniz yoksa, Google Cloud Console‘a giderek yeni bir proje oluşturmanız gerekmektedir. Projenize anlamlı bir isim verin ve bir faturalandırma hesabı bağladığınızdan emin olun. Vertex AI servisleri ücretli olduğundan, faturalandırma hesabı olmadan API’ları kullanamazsınız.

Gerekli API’leri Etkinleştirme

Apps Script’ten Vertex AI’a erişmek için Google Cloud projenizde belirli API’leri etkinleştirmeniz gerekir:

• Vertex AI API: Bu, Vertex AI’ın temel API’sidir ve tüm yapay zeka modellerine erişim sağlar.
• IAM API: Kimlik ve Erişim Yönetimi (IAM) API’si, hizmet hesaplarının yönetimi için gereklidir.

Bu API’leri Cloud Console’daki “API’ler ve Hizmetler” > “Kitaplık” bölümünden arayarak etkinleştirebilirsiniz.

Hizmet Hesabı Oluşturma ve Yetkilendirme

Apps Script’in Vertex AI’a güvenli bir şekilde erişebilmesi için bir hizmet hesabı kullanmak en iyi yöntemdir. Hizmet hesabı, uygulamanızın kimliğini temsil eder.

1. Cloud Console’da “IAM ve Yönetici” > “Hizmet Hesapları” bölümüne gidin.
2. “Hizmet Hesabı Oluştur” butonuna tıklayın.
3. Hesabınıza bir isim verin ve bir açıklama ekleyin.
4. Bu hizmet hesabına aşağıdaki IAM rollerini atayın:
   • Vertex AI Kullanıcısı (Vertex AI User)
   • Hizmet Hesabı Token Oluşturucu (Service Account Token Creator) – Bu rol, Apps Script’in hizmet hesabı adına kimlik doğrulama tokenları oluşturabilmesi için gereklidir.
5. Hizmet hesabını oluşturduktan sonra, üzerine tıklayarak detaylarına gidin. “Anahtarlar” sekmesine tıklayın ve “Anahtar Ekle” > “Yeni anahtar oluştur” seçeneğini seçin. Anahtar türü olarak “JSON” seçin ve oluşturun. Bu JSON dosyası, hizmet hesabınızın özel anahtarını içerir ve çok gizli tutulmalıdır. Bu dosyanın içeriğini daha sonra Apps Script’te kullanacağız.

Apps Script Projesi Oluşturma ve Yetkilendirme

Şimdi sıra Apps Script ortamında projemizi hazırlamaya geldi.

Yeni Bir Apps Script Projesi Başlatma

Apps Script projesi oluşturmak için iki ana yol vardır:

1. Bağımsız Komut Dosyası: script.google.com adresine giderek yeni bir proje oluşturabilirsiniz. Bu, genel amaçlı otomasyonlar için idealdir.
2. Bağlı Komut Dosyası: Bir Google E-Tablosu, Dokümanı veya Formu içinden “Uzantılar” > “Apps Script” yolunu izleyerek ilgili dosyaya bağlı bir komut dosyası oluşturabilirsiniz. Bu, belirli bir Google Workspace dosyasıyla etkileşim kuracak uygulamalar için kullanışlıdır.

Projenizi oluşturduktan sonra, varsayılan Code.gs dosyası açılacaktır.

Apps Script ve Google Cloud Projesini Bağlama

Apps Script projenizi, oluşturduğunuz Google Cloud projenize bağlamanız gerekmektedir. Bu, Apps Script’in Cloud projenizin kaynaklarına (API’ler, hizmet hesapları) erişebilmesini sağlar.

1. Apps Script projenizin sol menüsünden “Proje Ayarları” (çark simgesi) bölümüne gidin.
2. “Google Cloud Platform (GCP) Projesi” başlığı altında, daha önce oluşturduğunuz Google Cloud projenizin proje numarasını veya kimliğini girin ve “Proje Ayarla” butonuna tıklayın.

Bu adım, Apps Script’inizin Google Cloud projenizin kimlik doğrulama ve yetkilendirme mekanizmalarını kullanabilmesini sağlar.

Yetkilendirme Kapsamları (Scopes) Ayarlama

Apps Script’inizin harici API’lara erişebilmesi için belirli yetkilendirme kapsamlarına (scopes) ihtiyacı vardır. Bu kapsamlar, Apps Script projenizin hangi kaynaklara erişebileceğini belirtir. appsscript.json manifest dosyasını düzenleyerek bu kapsamları belirleyebilirsiniz.

1. Apps Script düzenleyicisinde sol menüden “Proje Ayarları”na gidin.
2. “Manifest dosyasını düzenleyicide göster” seçeneğini işaretleyin. Bu, appsscript.json dosyasını açacaktır.
3. appsscript.json dosyasının içeriğini aşağıdaki gibi güncelleyin (eğer yoksa oauthScopes anahtarını ekleyin):

{
  "timeZone": "America/New_York",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

• https://www.googleapis.com/auth/cloud-platform: Bu kapsam, Apps Script'in Google Cloud kaynaklarına (Vertex AI dahil) tam erişim sağlamasına izin verir.
• https://www.googleapis.com/auth/script.external_request: Bu kapsam, Apps Script'in UrlFetchApp kullanarak harici HTTP istekleri yapabilmesi için gereklidir.

Bu değişiklikleri kaydettikten sonra, komut dosyanızı ilk kez çalıştırdığınızda veya yetkilendirme gerektiren bir işlevi çağırdığınızda, Google sizden bu kapsamlar için izin isteyecektir.

Vertex AI API'larına Apps Script'ten Erişim

Artık Apps Script projemiz hazır olduğuna göre, Vertex AI API'larına nasıl HTTP istekleri yapacağımızı ve kimlik doğrulamasını nasıl yöneteceğimizi inceleyelim.

UrlFetchApp ile HTTP İstekleri Yapma

Apps Script'te harici API'larla etkileşim kurmanın birincil yolu UrlFetchApp servisidir. Bu servis, HTTP GET, POST, PUT gibi istekleri yapmanıza olanak tanır.

Vertex AI API'ları genellikle POST istekleri bekler ve istek gövdesinde JSON formatında veriler gönderilir. Yanıtlar da genellikle JSON formatında döner.

Kimlik Doğrulama (Authentication) Mekanizması

Vertex AI API'larına yapılan her istek, geçerli bir kimlik doğrulama tokenı ile imzalanmalıdır. Daha önce oluşturduğumuz hizmet hesabı ve JSON anahtarı burada devreye girer. Apps Script'te hizmet hesabı kimlik doğrulaması için OAuth2 for Apps Script kütüphanesini kullanmak en pratik ve güvenli yoldur.

OAuth2 Kütüphanesini Ekleme:

1. Apps Script projenizde sol menüden "Kitaplıklar" (kitap simgesi) bölümüne tıklayın.
2. "Kitaplık Ekle" alanına aşağıdaki kimliği yapıştırın: 1B7XdJ_TSnpT0_L377f0G77x_603g_Gf8q_7r0f_500
3. "Ara" butonuna tıklayın. "OAuth2" adında bir kütüphane bulmalısınız.
4. En son sürümü seçin ve "Ekle" butonuna tıklayın.

Hizmet Hesabı Bilgilerini Saklama:

Daha önce indirdiğiniz hizmet hesabı JSON dosyasını açın. İçindeki private_key ve client_email değerlerini almanız gerekecek. Bu bilgileri Apps Script'in "Proje Ayarları" bölümündeki "Komut Dosyası Özellikleri" (Script Properties) altına ekleyerek güvenli bir şekilde saklayabilirsiniz.

1. Apps Script projenizde sol menüden "Proje Ayarları" (çark simgesi) bölümüne gidin.
2. "Komut Dosyası Özellikleri" bölümünde "Özellik Ekle" butonuna tıklayın.
3. İki yeni özellik ekleyin:
   • Anahtar: PRIVATE_KEY, Değer: JSON dosyanızdaki private_key değeri (-----BEGIN PRIVATE KEY----- ile başlayan ve -----END PRIVATE KEY----- ile biten tüm metin)
   • Anahtar: CLIENT_EMAIL, Değer: JSON dosyanızdaki client_email değeri
4. "Özellikleri Kaydet" butonuna tıklayın.

Erişim Tokenı Oluşturma Fonksiyonu:

function getServiceAccountAccessToken() {
  const scriptProperties = PropertiesService.getScriptProperties();
  const privateKey = scriptProperties.getProperty('PRIVATE_KEY');
  const clientEmail = scriptProperties.getProperty('CLIENT_EMAIL');
  const projectId = 'YOUR_GCP_PROJECT_ID'; // GCP Proje ID'nizi buraya girin

  if (!privateKey || !clientEmail || !projectId) {
    throw new Error('Service account credentials or Project ID are missing in Script Properties.');
  }

  const service = OAuth2.createService('VertexAI')
      .setPrivateKey(privateKey)
      .setIssuer(clientEmail)
      .setScope('https://www.googleapis.com/auth/cloud-platform')
      .setTokenUrl('https://oauth2.googleapis.com/token');

  if (service.has  Access()) {
    return service.getAccessToken();
  } else {
    throw new Error('Could not retrieve access token: ' + service.getLastError());
  }
}

Yukarıdaki kodda YOUR_GCP_PROJECT_ID yerine kendi Google Cloud proje kimliğinizi girmeyi unutmayın.

Vertex AI Endpoint Yapısı

Vertex AI API'larına yapılan isteklerin URL'leri belirli bir yapıya sahiptir:

https://[LOCATION]-aiplatform.googleapis.com/v1/projects/[PROJECT_ID]/locations/[LOCATION]/publishers/google/models/[MODEL_ID]:predict

• [LOCATION]: Genellikle us-central1 veya europe-west4 gibi bir bölge.
• [PROJECT_ID]: Google Cloud proje kimliğiniz.
• [MODEL_ID]: Kullanmak istediğiniz Vertex AI modelinin kimliği (örn. gemini-pro, text-bison).
• :predict: Genellikle tahminleme veya içerik oluşturma işlemleri için kullanılan API metodu. Generative AI modelleri için :generateContent de kullanılabilir.

Örnek Bir API Çağrısı Şablonu

Aşağıda, bir Vertex AI API çağrısı için genel bir şablon bulunmaktadır:

function callVertexAI(modelId, payload) {
  const accessToken = getServiceAccountAccessToken();
  const projectId = 'YOUR_GCP_PROJECT_ID'; // GCP Proje ID'nizi buraya girin
  const location = 'us-central1'; // Kullanmak istediğiniz bölgeyi buraya girin

  const endpoint = https://${location}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}/publishers/google/models/${modelId}:predict;

  const options = {
    method: 'post',
    contentType: 'application/json',
    headers: {
      Authorization: 'Bearer ' + accessToken
    },
    payload: JSON.stringify(payload),
    muteHttpExceptions: true // Hataları yakalamak için true yapın
  };

  try {
    const response = UrlFetchApp.fetch(endpoint, options);
    const responseCode = response.getResponseCode();
    const responseText = response.getContentText();

    if (responseCode === 200) {
      return JSON.parse(responseText);
    } else {
      console.error(Vertex AI API hatası: ${responseCode} - ${responseText});
      throw new Error(Vertex AI API hatası: ${responseCode} - ${responseText});
    }
  } catch (e) {
    console.error('API çağrısı sırasında hata oluştu: ' + e.message);
    throw e;
  }
}

Bu fonksiyon, bir model kimliği ve bir JSON yükü alarak Vertex AI'a istek gönderir ve yanıtı JSON olarak döndürür.

Pratik Bir Örnek: Metin Oluşturma

Şimdi öğrendiklerimizi kullanarak pratik bir örnek yapalım: Vertex AI'ın Gemini modelini kullanarak metin oluşturma.

Senaryo: Kullanıcıdan Gelen Metni Özetleme

Bir Google E-Tablosu'ndaki bir hücreye yazılan uzun bir metni, Vertex AI'ın Gemini modelini kullanarak özetleyelim ve özetlenmiş metni başka bir hücreye yazalım.

Vertex AI Generative AI Studio Model Seçimi

Bu örnek için Google'ın güçlü üretken yapay zeka modellerinden biri olan gemini-pro modelini kullanacağız. Bu model, metin tabanlı görevler için optimize edilmiştir.

Apps Script Kodunun Yazılması

Aşağıdaki kodu Apps Script projenizin Code.gs dosyasına yapıştırın. Bu kod, yukarıdaki getServiceAccountAccessToken ve callVertexAI fonksiyonlarını da içermelidir.

function getServiceAccountAccessToken() {

  const scriptProperties = PropertiesService.getScriptProperties();

  const privateKey = scriptProperties.getProperty('PRIVATE_KEY');

  const clientEmail = scriptProperties.getProperty('CLIENT_EMAIL');

  const projectId = 'YOUR_GCP_PROJECT_ID'; // Kendi GCP Proje ID'nizi buraya girin

  if (!privateKey || !clientEmail || !projectId) {

    throw new Error('Service account credentials or Project ID are missing in Script Properties.');

  }
  const service = OAuth2.createService('VertexAI')

      .setPrivateKey(privateKey)

      .setIssuer(clientEmail)

      .setScope('https://www.googleapis.com/auth/cloud-platform')

      .setTokenUrl('https://oauth2.googleapis.com/token');
  if (service.hasAccess()) {

    return service.getAccessToken();