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

Mini ders 15 / 30 · Hesaplar ve erişim

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

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.

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

Bu derste ne öğreneceksiniz?

  • 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.
Açıklama, çözülmüş örnek ve alıştırma

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.

Başlamak için gereken beceriler

Bu dersleri bitirmiş olmanız şart değil; gereken beceriler sizde zaten varsa buradan başlayabilirsiniz. Hazır değilseniz bağlantılardaki hazırlık derslerini açın. Başlangıç dosyaları verildiği için önceden kişisel bir siteniz olması gerekmiyor.

  1. Web sitenizi GitHub üzerinden nasıl yayımlarsınız?

    Bir alıştırma deposunu barındırma hizmetine bağlayın.

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.

Konuyu anlayalım

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

Buradan başlayınUygulama dosyaları

Dosyaları aşağıdan açabilir veya tek tek indirebilirsin. Projeyi kaydederken dosya adlarında gösterilen klasör yapısını koru.

Sıra sizde

Hangi değer ziyaretçinin sayfasına gitmemeli ve asistandan hangi kanıtı incelemesini isteyeceksiniz?

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

Örnek gizlilik planı: “GEMINI_API_KEY özel sağlayıcı kimlik bilgisi. LAB_TOKEN, o anahtarın başka adı değil, ayrı deneme erişim kodu. Asistan, yanlışlıkla kimlik bilgisi sızması için sunulan herkese açık betikleri ve tarayıcı isteklerini inceleyecek.”

Özel bir dosya adı tek başına kanıt değildir: Derleme yine de içeriğini herkese açık çıktıya kopyalayabilir. Gerçek değerleri ekran görüntülerinden ve paylaşılan notlardan uzak tutacağım.

İyi bir cevap neleri içermeli?

  • Sağlayıcı anahtarını sır, deneme erişim kodunu ayrı uygulama sınırı olarak tanımlar.
  • Yanlışlıkla anahtar açığa çıkmasını incelemek için herkese açık dosyaları ve tarayıcı isteklerini belirtir.
Nasıl çalışır? (isteğe bağlı)

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.

Ek teknik alıştırma

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 1 · API anahtarlarını tarayıcıya göndermeden nasıl kullanırsınız?

Verilen korumalı işlemi başlatın

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

Açıklama, çözülmüş örnek ve alıştırma

Konuyu anlayalım

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.

Bu adımda kullanılan dosyalar

Buradan başlayınUygulama dosyaları

Dosyaları aşağıdan açabilir veya tek tek indirebilirsin. Projeyi kaydederken dosya adlarında gösterilen klasör yapısını koru.

Sıra sizde

İşlem çalıştı mı; özel kurulum veya sağlayıcı aşamasında hâlâ ne engelli?

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

Örnek hazırlık sonucu: “Eksiksiz proje yerel proxy adresinde açıldı. Deneme erişim koduyla sunucu işlemi web sitesi sunucusunu kısaca açıkladı. Sağlayıcı kimlik bilgileri ve model seçimi özel ortamda kaldı.”

Takılan örnek: “Uygulama çalışıyor ama sağlayıcı kullanılabilir kota olmadığını bildiriyor; başarılı yanıt gözlenmedi.” Tekrar istek göndermeden hesabınızın izinli modellerini, sınırlarını ve olası ücretlerini kontrol edin; bu ders ücretsiz veya sınırsız çağrı vaat etmez.

İyi bir cevap neleri içermeli?

  • Gerçek yerel uygulama adresini ve izinli bir işlemi ya da tam yapılandırma/sağlayıcı engelini kaydeder.
  • Sağlayıcı kimlik bilgisini/modeli sunucuda tutar ve çağrıdan önce hesabın kullanım koşullarını kontrol eder.
Nasıl çalışır? (isteğe bağlı)

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

Ek teknik alıştırma

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 2 · API anahtarlarını tarayıcıya göndermeden nasıl kullanırsınız?

Gizliliği ve hatayı birlikte kontrol edin

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

Açıklama, çözülmüş örnek ve alıştırma

Konuyu anlayalım

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

Buradan başlayınUygulama dosyaları

Dosyaları aşağıdan açabilir veya tek tek indirebilirsin. Projeyi kaydederken dosya adlarında gösterilen klasör yapısını koru.

Sıra sizde

Herkese açık çıktı kontrolü ve reddedilen deneme gerçekte ne gösterdi?

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

Örnek gizlilik/hata kaydı: “Asistan herkese açık çıktıyı ve kendi sunucuma giden tarayıcı isteğini inceledi; sağlayıcı anahtarı yoktu. Yanlış deneme kodu reddedildi. Geçici deneme kurulumunda özel sağlayıcı yapılandırması kaldırılınca işlem uydurma açıklama göstermek yerine hata verdi.”

Bu, tam güvenlik denetimi değil incelenen sınırın kaydıdır. Herkese açık çıktıda anahtar bulunursa o derlemeyi paylaşmayı durdurun; tekrar kullanmadan önce açığa çıkan kimlik bilgisini sağlayıcı üzerinden değiştirin.

İyi bir cevap neleri içermeli?

  • Sağlayıcı sırrını tekrar yazmadan hangi herkese açık çıktı/isteklerin incelendiğini söyler.
  • Reddedilen erişim ve eksik yapılandırma denemelerini hata olarak kaydeder.
Nasıl çalışır? (isteğe bağlı)

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.

Ek teknik alıştırma

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 3 · API anahtarlarını tarayıcıya göndermeden nasıl kullanırsınız?

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.

Açıklama, çözülmüş örnek ve alıştırma

Konuyu anlayalım

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

Buradan başlayınUygulama dosyaları

Dosyaları aşağıdan açabilir veya tek tek indirebilirsin. Projeyi kaydederken dosya adlarında gösterilen klasör yapısını koru.

Sıra sizde

Değişen işlemi ve gerçekten çalıştırdığınız gizlilik/geçerli/geçersiz kontrolleri sunun.

Hazırlanacak çıktı: Verilen işlem için hassas bilgileri çıkarılmış anahtar sınırı ve geçerli/geçersiz istek kaydı.

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

Örnek değişiklik kaydı: “Sabit işlem artık DNS’i iki cümlede anlatıyor. İzinli deneme çağrısı o konuyu döndürdü; yanlış deneme kodu reddedildi; herkese açık çıktı kontrolünde hâlâ sağlayıcı anahtarı yoktu.”

“Bunu tanımadığım kişilere açmadan önce gerçek kimlik doğrulama, kalıcı kullanım sınırları ve sağlayıcı bütçesi takibi hâlâ gerekiyor.” Ortak deneme kodu küçük bir uygulama sınırıdır; tam bir herkese açık hizmetin kanıtı değildir.

İyi bir cevap neleri içermeli?

  • Yalnızca sunucudaki anahtar/model ayarlarını koruyarak sabit yanıt konusunu DNS’e değiştirir.
  • İzinli ve reddedilen çağrıları tekrarlar; herkese açık kullanım için gereken maliyet/erişim kontrollerini belirtir.
Nasıl çalışır? (isteğe bağlı)

Ö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.

Ek teknik alıştırma

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.