Mini ders · Türkçe

API anahtarlarını tarayıcıya göndermeden nasıl kullanırsınız?

Sağlayıcı anahtarını ziyaretçinin tarayıcısından uzak tutmak ve izin verilen/reddedilen istekleri doğrulamak için verilen sunucu destekli örneği kullanın.

Etkileşimli derse başlaDers notlarını oku

Bu ders kimler için?

Web sitesini yapay zekâya veya başka ayrıcalıklı hizmete bağlayanlar için. Kodlama asistanı hazır projenin bağlantılarını kurabilir; sunucu kodu yazmak yerine sırrınızın nerede kullanılabileceğini anlamanız gerekir.

Başlamadan önce

Kendi Google AI Studio API erişiminiz ve ayrı Netlify function deneme projeniz gerekir. Eksiksiz uygulama paketi ve özel ortam kurulumu için kodlama asistanı kullanın. İstek göndermeden önce modelin ve hesabın kullanım sınırlarını, olası ücretler dahil, doğrulayın. Uygulama yalnızca sahibinin elinde tuttuğu ayrı deneme kodu kullanır; hazır bir herkese açık AI hizmeti değildir.

Tahmini süre: 20–32 dk

Hazır örnek dosyalarla, gerekli hesap ve araçlar kurulmuşken çalışma tahmini. Kurulum, yayınlanma sırası ve e-posta/DNS beklemeleri ayrıca zaman alabilir. Sağlayıcı ve hesap ayarı daha uzun sürebilir. Kullanım, hesabınızın güncel koşullarına ve kotasına tabidir.

Neler öğreneceksin?

  • Sağlayıcı sırrını yalnızca özel sunucu ortamına koyun.
  • Anahtarı ziyaretçilere açığa çıkarmadan verilen işlemi çalıştırın.
  • Başarılı ve reddedilen erişim denemelerini kontrol edin.

Uygulama dosyaları

Adım 1

Hangi değerin özel kalması gerektiğini bilin

Tarayıcı, sağlayıcı sırrını almadan özelliğinizi kullanmalıdır.

Verilen projeyi asistanınızla açın. Sağlayıcı anahtarını özel hesap değeri, ayrı alıştırma kodunu ise bu küçük laboratuvar için sahibin erişim denetimi olarak belirleyin.

Derleme değeri herkese açık betiklere kopyalıyorsa dosyanın .env adını taşıması yeterli değildir. Asistandan ziyaretçiye gerçekten sunulan dosyaları incelemesini isteyin.

Somut bir örnek

Gizli form alanı yine tarayıcıya aittir ve sağlayıcı anahtarını saklayamaz.

Bu hazır API anahtarı atölyesini aç ve run-locally.txt kurulumunda yol göster. Sağlayıcı anahtarı ve model seçimi sunucuda kalsın; ayrı alıştırma erişim kodu kullan. Sırları herkese açık dosyalara koyma veya paylaşılan iletilere yapıştırmamı isteme. Tarayıcının aldıklarını incelememe, hem izin verilen hem reddedilen istekleri sınamama yardım et. Uç noktayı benim uygulamamı istemek yerine gözlemlenebilir kanıtı açıkla.

Bu adımda kullanılan dosyalar

Start hereUygulama dosyaları

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Ayrıcalıklı API anahtarını tarayıcı koduna koymayın

Ziyaretçinin tarayıcısı ona gönderdiğiniz bütün dosyaları inceleyebilir.

Sağlayıcı anahtarı harcama veya ayrıcalıklı işlem yetkisi verebilir. Bunu açık JavaScript’e, gizli form alanına veya tarayıcı paketi hazırlanırken yerine yazılan ortam değişkenine koymak, yine ziyaretçiye göndermek demektir.

Örnek, sunucu işleviniz üzerinden Gemini’ye tek sabit öğretici soru sorar. Tarayıcı yanıtı alır; sağlayıcı anahtarı sunucu ortamında kalır. Her anahtar gizli değildir: Supabase publishable anahtarları erişim kurallarıyla tarayıcıda kullanılmak için tasarlanmıştır, secret anahtarları ise değildir.

Çözülmüş örnek

insecure-example.txt dosyasını açın. Sahte değer görünür çünkü gönderilen kodun içindedir. Satırı küçültmek veya sıkıştırmak okumayı zorlaştırır ama onu kimin aldığını değiştirmez.

Extra implementation exercise

Anahtar .env içinde tutulup derleme sırasında açık JavaScript paketine yazılıyor. Ziyaretçiden gizli kalır mı?

Çözülmüş örneği göster

Hayır. Açık pakete eklendikten sonra ilk dosyasının neresi olduğu önemli değildir. Ayrıcalıklı işlemi sunucu işlevine taşıyın ve değeri orada tutun.

  • Anahtarın teslim edilen pakete kadar nereye gittiğini izler.
  • Sunucu ortamıyla tarayıcı derlemesine değer yerleştirmeyi ayırır.

Adım 2

Verilen korumalı işlemi başlatın

Mevcut sunucu yolunu asistan yapılandırsın.

Asistanla run-locally.txt ve server-env.example.txt dosyalarını izleyin. Amaçlanan hesabı/modeli ve kullanım koşullarını doğrulayın; sağlayıcı anahtarını sunucuda özel olarak ayarlayın ve ayrı deneme kodu üretin. Eksiksiz projeyi çalıştırıp yerel uygulama adresini açın. Bu kurulum kontrolleri zorunlu, fonksiyon kodunu yazmak isteğe bağlıdır.

Tarayıcı sunucu özelliğinizle konuşmalı, sunucu ise sağlayıcıyı özel olarak çağırmalıdır. Kurulum, erişim veya kota başarısızsa yanıt uydurmak yerine o aşamayı bildirin.

Somut bir örnek

Formun alıştırma kodu Google sağlayıcı anahtarı değildir.

Gemini generateContent API · Gemini API anahtarları · Gemini: güncel model ID’leri ve özellikleri · Node.js: desteklenen sürümlerin durumu

Bu adımda kullanılan dosyalar

Start hereUygulama dosyaları

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Sağlayıcıyı kendi sunucu adresiniz üzerinden çağırın

Sunucuyu ayarlayın, sonra yalnızca bu özelliğin gerektirdiği küçük isteği gönderin.

netlify/functions/mini-explain.mjs dosyasını okuyun, ayrı projeyi yayımlayın ve sunucuda GEMINI_API_KEY, GEMINI_MODEL, LAB_TOKEN ayarlayın. Eski bir eğitimden model adı kopyalamak yerine hesabınızda desteklenen metin modelini seçin.

Ayrı deneme kodunu forma girin. Tarayıcı /.netlify/functions/mini-explain çağırır; bu işlev sabit Google HTTPS adresine x-goog-api-key ile gider. Kod, uygulamayı sahibinin kullanımına kısıtlar; Gemini kimlik bilgisi veya herkese açık kullanım için eksiksiz kota sistemi değildir.

GEMINI_MODEL, ekran görüntüsündeki görünen ad değil, kendi API hesabınızda kullanılabilen tam model ID’sidir. generate aynı sunucu dosyasındaki yardımcı işlevdir. Ne anahtar ne yardımcı işlev public/ içinde olmalı. İstek geçerli olsa da sağlayıcının kotası yoksa veya hizmete ulaşılamıyorsa başarısız olabilir.

Yerel çalışma sırasının tamamı için run-locally.txt dosyasını açın: kökteki özel ortamı hazırlayın, yalnızca deneme projesini bağlayın ve Netlify işlevlerine istek ileten yerel aracı başlatın. server-env.example.txt gerçek sırlar olmadan değişken adlarını listeler. Yalnızca HTML’yi açmak sunucuyu çalıştırmaz.

Aşağıdaki güncel model kılavuzunu kullanın veya kendi ortamınızla özel kök klasörden list-text-models.mjs çalıştırın. Anahtarı yazdırmadan hesabın görebildiği generateContent adaylarını listeler. Desteklenen metin modelini seçin, koşul ve kotayı kontrol edip tam API ID’sini sunucudaki GEMINI_MODEL değerine yazın.

İlk işlev isteğinden önce model listeleme aracını çalıştırıp systemInstruction dahil burada kullanılan generateContent alanlarını destekleyen güncel metin modelini seçin. Liste adayları gösterir; kotayı veya bütün model yeteneklerini doğrulamaz. netlify/functions/mini-explain.mjs dosyasının tamamı sunucuda çalışır; public/app.js her ziyaretçiye gönderilir. Barındırma paketinin işlev zaman sınırını da kontrol edin: sağlayıcı için 20 saniye beklemek, daha kısa sunucu sınırını uzatmaz.

Çözülmüş örnek

Soru sunucuda sabittir; istemci bu yolu istediği kadar büyük sorular gönderen bir araca çeviremez. İşlev yanıt uzunluğunu da sınırlar ve sağlayıcı isteğini en fazla 20 saniye bekler.

Gemini generateContent API · Gemini API anahtarları · Gemini: güncel model ID’leri ve özellikleri · Node.js: desteklenen sürümlerin durumu

Extra implementation exercise

Hangi iki istek yapılmalı, bunlardan hangisi tarayıcının Network araçlarında görünmemeli?

Çözülmüş örneği göster

Tarayıcı kendi işlevinize giden isteği ve dönen yanıtı gösterir. Sağlayıcı isteğini sunucu yapar; anahtar taşıyan Google çağrısı tarayıcı isteği olarak görünmemelidir.

  • Tarayıcının kendi site işlevine yaptığı isteği görür.
  • Google’a kimlik bilgisiyle yapılan isteği sunucuda tutar.

Adım 3

Gizliliği ve hatayı birlikte kontrol edin

Faydalı yanıt, açığa çıkan anahtarı mazur göstermez.

Asistandan gönderilen herkese açık dosyalarda ve tarayıcı isteklerinde sağlayıcı sırrını aramaya yardım etmesini, ancak bunu paylaşılan kayıtlarda göstermemesini isteyin. Gözden çıkarılabilir projede yanlış alıştırma kodunu ve eksik yapılandırma durumunu deneyin.

Gerçek anahtar tarayıcı dosyalarında/isteklerinde görünmemelidir. Reddedilen veya kullanılamayan istekler, kullanılabilir yeniden deneme yolu ile hata olarak kalmalıdır.

Somut bir örnek

İkna edici yanıt ve app.js içinde açığa çıkan anahtar, hâlâ tamamlanmamış görevdir.

Bu adımda kullanılan dosyalar

Start hereUygulama dosyaları

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Yanıtı ve anahtarın nerede kaldığını birlikte doğrulayın

Başarılı yanıt, anahtarın gizli kaldığını tek başına kanıtlamaz.

Anahtarı ekran görüntüsüne veya ortak günlüğe yapıştırmadan, yayımlanmış açık HTML ve betiklerde gerçek değeri arayın. Tarayıcı isteklerini inceleyin: sahibin girdiği deneme kodu görülebilir ama Gemini anahtarı görünmemeli.

Gözden çıkarılabilir projede yanlış kodu ve eksik sağlayıcı ayarını deneyin. Hata hata olarak kalmalı. 429 kota/istek sınırını, 401 veya 403 erişim/ayar sorununu gösterebilir. Bunları uydurma bir yapay zekâ yanıtına dönüştürmeyin.

Çözülmüş örnek

Doğru deneme kodu ve geçerli sağlayıcı ayarları gerçek yanıt döndürmeli. Aynı adrese yanlış kodla istek, sağlayıcı hiç çağrılmadan reddedilmeli.

Extra implementation exercise

Yanıt çalışıyor ama sağlayıcı anahtarı public/app.js içinde de var. İş tamam mı?

Çözülmüş örneği göster

Hayır. Anahtarı açık dosyalardan çıkarın, açığa çıktığı için iptal edip yenisini üretin ve sunucu ayarını güncelleyin. Yeni yayını ve depo geçmişini kalan sızıntılar için kontrol edin.

  • Başarılı yanıtı tek başına yeterli kanıt saymaz.
  • Sızıntıyı kaldırıp açığa çıkan anahtarı yeniler.

Adım 4

Sınırlı tek bir değişikliği güvenli yapın

Özelliği değiştirirken sırrın sınırını koruyun.

Asistandan verilen sabit işlemi DNS'i kısaca açıklayacak şekilde uyarlamasını isteyin. Sunucudaki model/anahtar ayarlarını ve yalnızca sahibine açık alıştırma sınırını koruyun.

Hedeflenen yanıtı ve geçersiz erişim kodunu yeniden sınayın. Herkese açık kullanımdan önce gerçek kimlik doğrulamaya, kalıcı kullanım denetimlerine ve sağlayıcı bütçenizi izlemeye karar verin.

Somut bir örnek

Yanıtın konusunu değiştirmek, özel hesap değerlerini sayfaya taşımamalıdır.

Bu adımda kullanılan dosyalar

Start hereUygulama dosyaları

Open or download the files below. When saving a project, keep the folder paths shown in the filenames.

How it works (optional)

Ödeviniz: ikinci bir sabit işlemi sunucuya taşıyın

Erişimi yanlışlıkla genişletmeden aynı korumayı bilinçli olarak tekrarlayın.

Sunucudaki sabit soruyu DNS’yi iki cümlede açıklayacak şekilde değiştirin. Anahtar, model seçimi ve yanıt sınırı sunucuda kalsın; tarayıcı sağlayıcı anahtarını bilmesin.

Geçerli ve yanlış kodla sonuçları kaydedin. Herkese açmadan önce neler ekleyeceğinizi açıklayın: doğrulanmış kullanıcılar veya anlamlı başka erişim denetimi, kalıcı kullanım sınırları ve sağlayıcı bütçesini izleme.

Çözülmüş örnek

Sabit soruyu değiştirmek, sağlayıcının davranışını nereden yönettiğinizi anladığınızı gösterir. Tarayıcıdan gelişigüzel model, adres veya yanıt sınırı kabul etmek bu denetimi ortadan kaldırır.

Çözümün bütün adımlarını reference/assignment-walkthrough.txt dosyasında bulabilirsiniz. Adımları kendi sonucunuzla karşılaştırın; kontrol kaydını kendi projenizde gözlemlediklerinizle doldurun.

Extra implementation exercise

DNS sürümünü ve kısa bir erişim/veri ayrımı testi kaydı hazırlayın.

Çözülmüş örneği göster

Yalnızca sunucuda çalışan mini-explain içinde web sunucusu hakkındaki sabit soruyu 'Explain DNS in two sentences for a beginner.' olarak değiştirin; yani DNS’yi yeni başlayan birine iki cümlede açıklamasını isteyin. Anahtar ve model sunucu ortamında kalsın. Tam referans işlevi değişen yeri gösterir.

Tarayıcıya gönderilen betikleri ve Network isteklerini inceleyin. Tarayıcı kendi işlevinize gitmeli; GEMINI_API_KEY ile doğrudan Google’a gitmemeli. Sahibin yazdığı deneme kodu, sağlayıcı anahtarından ayrıdır.

Yanlış kod deneyin: sağlayıcı çağrısından önce reddedilmesini bekleyin. Kota veya ağ hatası, hazır başarılı yanıtla örtülmemeli. Gerçek sır açığa çıktıysa çıkarıp yenileyin; dosyayı sonradan yok saymak sızıntıyı geçersiz kılmaz.

  • Sağlayıcı sırrı tarayıcıya gönderilmez.
  • Yanlış erişim reddedilir ve gerçek sağlayıcı hatası açıkça görünür.

Ders işine yaradı mı?

Beğenebilir, faydalanacağını düşündüğün biriyle paylaşabilirsin.

Öğrenmeye devam edin

Diğer dersleri inceleyin