Firebase Cloud Functions — nedir, tetikleyiciler ve işlevler nasıl yazılır

Firebase Cloud Functions Nedir ve Nasıl Çalışır

Firebase Cloud Functions, Google Cloud Functions (GCF) üzerine inşa edilmiş, Firebase ekosistemine uyarlanmış bir bilgi işlem platformudur. İşlevler, bir modülden dışa aktarılan ve belirli bir olay türü için kaydedilen normal JavaScript veya TypeScript kodudur. Bir olay meydana geldiğinde (örneğin, bir kullanıcı kaydolduğunda veya bir dosya yüklediğinde), Firebase Cloud Functions ilgili kodu çalıştırır ve olay bağlamını iletir.

Cloud Functions mimarisi tek sorumluluk ilkesini izler: bir işlev, bir olay türünü işler ve tek bir atomik işlem gerçekleştirir. Örneğin, sendWelcomeEmail işlevi, Firebase Authentication'da yeni bir kullanıcı oluşturulduğunda tetiklenir ve bir hoş geldiniz e-postası gönderir. Bu tür bir yalıtım, hata ayıklamayı, test etmeyi ve işlevlerin farklı projelerde yeniden kullanılmasını basitleştirir.

Her işlev, geçici bir yaşam döngüsüne sahip izole bir kapsayıcıda çalışır. Maksimum yürütme süresi varsayılan olarak 60 saniyedir (HTTPS işlevleri — 9 dakika). Bir işlev zaman aşımı içinde tamamlanmazsa, istek 500 hatasıyla başarısız olur. Uzun süreli işlemler için, yeniden denemelerle Cloud Tasks veya Pub/Sub kullanın. Kapsayıcılar sonraki çağrılar için yeniden kullanılabilir (keep-alive), bu da ilk çağrıdan sonra soğuk başlangıçtaki gecikmeyi azaltır.

Çalışma Zamanı Ortamı ve Node.js Sürümleri

Firebase Cloud Functions, birden çok Node.js sürümünü destekler: 18, 20 ve 22 (yeni projeler için önerilir). Sürüm, package.json dosyasının engines alanında belirtilir. Firebase CLI, belirtilen sürüme göre çalışma zamanı ortamını otomatik olarak yapılandırır. Önemli: Firebase Cloud Functions, rastgele Docker kapsayıcılarının çalıştırılmasını desteklemez — ortam, Google Cloud Functions tarafından kesin olarak belirlenir.

Yeni projeler için, en son V8 optimizasyonlarını, geliştirilmiş ESM modül desteğini ve platform düzeyinde WebSocket desteğini içerdiğinden Node.js 22 önerilir. Bir proje, belirli bir Node sürümü için oluşturulmuş bağımlılıklar kullanıyorsa (örneğin, yerel C++ modülleri), uyumluluk ayrı ayrı kontrol edilmelidir — tüm yerel modüller GCF ortamında derlenmez.

Firebase Cloud Functions ve Google Cloud Functions Arasındaki Fark

Firebase Cloud Functions, önceden yüklenmiş Firebase SDK ve Firebase hizmetleriyle entegrasyon ile Google Cloud Functions etrafında bir sarmalayıcıdır. Geliştirici, tüm Firebase hizmetleri için yazılmış tetikleyiciler sağlayan firebase-functions SDK'sını kullanarak kod yazar. Google Cloud Functions, tetikleyicilerin Eventarc veya Pub/Sub aracılığıyla açıkça yapılandırıldığı daha düşük seviyeli bir platformdur.

Anahtar fark: Firebase Cloud Functions'ta bir tetikleyici, functions.firestore.document('path').onWrite() aracılığıyla bildirimsel olarak kaydedilirken, Google Cloud Functions'ta olay özelliği filtreleme ile Eventarc aracılığıyla yapılandırılır. Firebase Cloud Functions ayrıca, projenin hizmet hesabı kimlik bilgileriyle otomatik olarak başlatılan Admin SDK ile birlikte gelir ve ek yapılandırma olmadan tüm Firebase hizmetlerine tam erişim sağlar.

Tetikleyici Türleri: Hangi Olaylar Desteklenir

Firebase Cloud Functions, her biri belirli bir Firebase veya Google Cloud hizmetine karşılık gelen 8 tetikleyici kategorisini destekler. Tetikleyici, karşılandığında otomatik olarak bir işlevi çağıran bir koşuldur. Geliştirici, işlevin yaşam döngüsünü doğrudan yönetmez: Firebase CLI, tetikleyiciyi Google Cloud Eventarc'a kaydeder ve olay meydana geldiğinde bulut platformu işlevi çalıştırır.

En popüler tetikleyiciler Firestore tetikleyicileridir: onWrite, onCreate, onUpdate, onDelete. Firestore koleksiyonlarındaki belgeler değiştiğinde tetiklenirler. İşlev, değişiklikten önce ve sonra belgenin anlık görüntülerini alır, bu da değerleri karşılaştırmaya ve yalnızca belirli değişikliklere yanıt vermeye olanak tanır. Örneğin, bir sipariş durumu “beklemede”den “gönderildi”ye değiştiğinde, kullanıcıya bir push bildirimi gönderilebilir.

Authentication tetikleyicileri (onCreate, onDelete), bir kullanıcı hesabı oluşturulduğunda veya silindiğinde tetiklenir. Kullanıcı verilerini başlatmak için kullanılırlar: Firestore'da kullanıcı belgesi oluşturma, hoş geldiniz e-postası gönderme, analizlere yazma. Not: işlev, kullanıcı oluşturmayı iptal edemez — hesap zaten oluşturulduktan sonra yürütülür. Ön doğrulama için, Identity Platform'da bulunan Blocking Functions'ı kullanın.

HTTPS Tetikleyicileri ve CORS

HTTPS işlevleri (onRequest), HTTP üzerinden erişilebilen tam REST API uç noktaları oluşturmaya olanak tanır. Olay odaklı tetikleyicilerin aksine, HTTPS işlevleri https://{region}-{project}.cloudfunctions.net/{functionName} biçimindeki bir URL aracılığıyla çağrılır. Uç nokta bir tarayıcıdan veya mobil uygulamadan çağrılıyorsa CORS'un doğru yapılandırılması önemlidir. Firebase SDK, CORS başlıklarını otomatik olarak içermez — bunların ara yazılım aracılığıyla manuel olarak eklenmesi gerekir.

Mobil istemciler (Android, iOS) için CORS gerekli değildir çünkü yerel HTTP istemcileri, Kaynaklar Arası paylaşım ilkesiyle kısıtlanmaz. CORS yalnızca web istekleriyle ilgilidir. HTTPS işleviniz hem uygulamadan hem de web'den çağrılıyorsa, geliştirme için res.set('Access-Control-Allow-Origin', '*') veya üretim için izin verilen alan adları listesiyle evrensel CORS işleme ekleyin.

Pub/Sub ve Cloud Scheduler ile Zamanlama

Periyodik yürütme (cron görevleri) için Cloud Scheduler ve Pub/Sub kombinasyonunu kullanın. Cloud Scheduler, bir programa göre bir Pub/Sub konusuna bir mesaj gönderir ve Cloud Functions'ın onPublish tetikleyicisi bu mesajı işler. Firebase CLI, doğrudan cron sözdizimini desteklemez — zamanlama, Google Cloud konsolu veya Terraform aracılığıyla unix-cron biçiminde yapılandırılır: 0 3 * * * (her gün saat 3:00'te).

Örnek görevler: günlük bülten, eski verileri temizleme, rapor oluşturma, harici API'lerle senkronizasyon. Önemli: Cloud Scheduler, ücretli bir Google Cloud hizmetidir (iş başına ayda yaklaşık $2). Her tetikleme, ayrı bir işlev çağrısı olarak sayılır ve standart Cloud Functions ücretleri üzerinden faturalandırılır.

İşlevler Nasıl Yazılır ve Dağıtılır

Cloud Functions geliştirme, Firebase CLI aracılığıyla bir proje başlatmakla başlar: firebase init functions. Bu komut, bir index.js (veya index.ts) şablonu, bir package.json dosyası ve TypeScript yapılandırması (seçilirse) ile bir functions/ dizini oluşturur. Başlatma işleminden sonra, bir işlev yazmanız, modülden dışa aktarmanız ve dağıtmak için firebase deploy --only functions komutunu çalıştırmanız yeterlidir.

Her işlev, uygun tetikleyici yöntemi çağrılarak kaydedilir. Bir HTTPS işlevi örneği: exports.helloWorld = functions.https.onRequest((req, res) => { res.send(“Hello!”); }). Firebase Functions, asenkron bir model kullanır: olay odaklı tetikleyiciler (HTTPS olmayan) için işlevin bir Promise döndürmesi gerekir. Firebase, kapsayıcıyı sonlandırmadan önce Promise'in tamamlanmasını bekler. Bir Promise döndürülmezse, işlev asenkron işlemler tamamlanmadan sonlandırılabilir.

Yerel geliştirme, bir Cloud Functions öykünücüsü içeren Firebase Emulator Suite aracılığıyla yapılır. firebase emulators:start komutu, http://localhost:5001 adresinde erişilebilen işlevlerle yerel bir sunucu başlatır. Öykünücü, kod değiştiğinde anında yeniden yüklemeyi destekler ve üretim ortamından tamamen izole edilmiştir, bu da gerçek verileri riske atmadan test yapılmasına olanak tanır.

Bağımlılık ve Yapılandırma Yönetimi

Cloud Functions'ın bağımlılıkları package.json aracılığıyla yönetilir. Firebase yalnızca üretim bağımlılıklarını (dependencies, devDependencies değil) yükler. İşlev paketi boyutu, soğuk başlangıç süresini etkiler: bağımlılık sayısının en aza indirilmesi önerilir. Firebase Admin SDK için firebase-admin bağımlılığı önceden yüklenmiştir — manuel olarak eklenmesi gerekmez.

Gizli veriler (API anahtarları, tokenlar) işlev kodunda saklanmamalıdır. Yapılandırmayı depolamak için functions.config() kullanın: firebase functions:config:set stripe.key=“sk_...”. Değerler şifrelenir ve çalışma zamanında functions.config().stripe.key aracılığıyla kullanılabilir. Büyük serileştirilmiş yapılandırmalar için Google Cloud Secret Manager'ı kullanın.

Hata İşleme ve Günlüğe Kaydetme

Cloud Functions'ta günlüğe kaydetme, console.log, console.warn ve console.error aracılığıyla yapılır. Tüm günlükler otomatik olarak Google Cloud Logging'de toplanır ve Firebase konsolunda (Functions > Logs) kullanılabilir. Yapılandırılmış günlüğe kaydetme için, JSON biçimlendirmesini ve günlük düzeylerini destekleyen winston veya pino kitaplıklarını kullanın.

Hata işleme güvenilirlik için kritiktir: bir Promise'de işlenmeyen bir özel durum, işlevi bir hatayla sonlandırır ve ardından Firebase, üstel geri alma ile otomatik olarak yeniden dener. Yeniden deneme sayısı yapılandırılabilir: 0'dan sonsuza kadar. Olay odaklı tetikleyiciler için, harici hizmetlerdeki geçici arızalar sırasında bile her olayın işlenmesini sağlamak için yeniden denemelerin etkinleştirilmesi önerilir.

Soğuk Başlangıç ve Ölçeklendirme

Soğuk başlangıç (cold start), kod içeren kapsayıcının yeniden yüklendiği ve başlatıldığı, hareketsizlik döneminden sonraki bir işlevin ilk çağrılmasındaki gecikmedir. Firebase belgelerine (2026) göre, soğuk başlangıç, paket boyutuna, bağımlılık sayısına ve bölgeye bağlı olarak 200 ms ile 2 saniye arasında sürer. Kullanıcı arayüzü için 1 saniyeyi aşan bir gecikme fark edilir ve kullanıcı deneyimini etkileyebilir.

Soğuk başlangıcı en aza indirme yolları: bağımlılıkları en aza indirin, CommonJS'ye derlenmiş TypeScript kullanın, işlev paketi boyutunu küçültün, minimum etkin örnek sayısı belirleyin. Firebase Cloud Functions v2 (2. nesil), minInstances — istekleri işlemeye her zaman hazır, sıcak kapsayıcıların minimum sayısını ayarlamanıza olanak tanır. Kapsayıcıları sıcak tutmak, boşta kalma süresi için ücrete tabidir.

Cloud Functions'ın ölçeklendirmesi otomatik olarak gerçekleşir: istek hacmi arttıkça Firebase yeni kapsayıcılar oluşturur. Varsayılan olarak, maksimum paralel örnek sayısı 3000'dir (Google Cloud proje kotası). Her örnek aynı anda bir isteği işler. Bir işlev hızlıysa (100 ms'nin altında), bir örnek saniyede 10 isteğe kadar işleyebilir ve proje başına saniyede 30.000 isteğe kadar tepe verim sağlar.

minInstances ve maxInstances Yapılandırması

minInstances, belirli sayıda kapsayıcıyı ayıran ve onları sıcak tutan bir parametredir. Soğuk başlangıç gecikmesinin kabul edilemez olduğu kritik HTTPS işlevleri için önerilir. Örneğin, bir kimlik doğrulama uç noktası için minInstances: 1 ayarlayın. maxInstances, maksimum paralel örnek sayısını sınırlar ve ani trafik artışları sırasında kontrolsüz maliyet artışını önlemek için kullanışlıdır.

Yapılandırma kodda yapılır: functions.runWith({ minInstances: 1, maxInstances: 10 }). Önemli: minInstances, kapsayıcılar sürekli çalıştığı için maliyeti artırır. Test projeleri için minInstances devre dışı bırakılmalıdır. Üretim için, tüm genel HTTPS işlevleri için minInstances ve 1 saniyelik gecikmenin kritik olmadığı olay odaklı tetikleyiciler için 0 önerilir.

Dağıtım Bölgeleri

Dağıtım bölgesi, son kullanıcılara yönelik gecikmeyi ve giden trafiğin maliyetini etkiler. Firebase Cloud Functions, 30'dan fazla Google Cloud bölgesinde kullanılabilir. Mobil uygulamalar için, hedef kitlenize en yakın bölgeyi seçin: Amerika için us-central1, Avrupa için europe-west1, Asya için asia-east2. Bölge, işlevi yeniden dağıtmadan değiştirilemez.

Bölge değişikliği, kodda region parametresi aracılığıyla yapılır: functions.region('europe-west1'). Tek bir dosyadaki tüm işlevler farklı bölgelere sahip olabilir. Küresel projeler için, işlevlerin birden çok bölgede dağıtılması ve trafik dağıtımı için Cloud Load Balancing kullanılması önerilir, ancak çoğu mobil uygulama için doğru seçildiğinde tek bir bölge yeterlidir.

Firebase Cloud Functions için Kod Örnekleri

TypeScript'te Cloud Functions'ın pratik örneklerine bakalım. Kod, ES modül sözdizimi ile Firebase Functions SDK v2'yi (2. nesil) kullanır. Örnekler, bir kullanıcı oluşturma olayının işlenmesini, bir resim yüklemesinde küçük resim oluşturulmasını ve bir REST API için basit bir HTTPS uç noktasını içerir. Tüm işlevler asenkrondur ve uygun kapsayıcı sonlandırması için bir Promise döndürür.

Çalıştırmadan önce, Firebase CLI'nin 13+ sürümüne güncellendiğinden emin olun: npm install -g firebase-tools. v2 işlevleri, Blaze fiyatlandırma planını gerektirir. Başlatma: TypeScript seçiliyken firebase init functions.

Kullanıcı Kaydını İşleme

İlk örnek — yeni bir kullanıcı kaydolduğunda Firestore'da bir belge oluşturma. İşlev, auth.user().onCreate olayı tarafından tetiklenir ve users/{uid} koleksiyonuna temel bir profil yazar. Bu, kayıtlı her kullanıcının gerekli alanlarla bir belgeye sahip olmasını sağlar.

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

createUserProfile işlevi asenkrondur — Firebase'in sonlandırmadan önce beklediği bir Promise döndürür. Firestore'a yazma başarısız olursa (örneğin, yetersiz izinler nedeniyle), işlev otomatik olarak yeniden denenir (yeniden deneme etkinse). “free” değerine sahip role alanı, resource.data.role öğesini gerekli erişim düzeyiyle karşılaştırarak Firestore Security Rules'da doğrudan ücretsiz plan kısıtlamalarını uygulamaya olanak tanır.

Resim Yüklemede Küçük Resim Oluşturma

İkinci örnek — bir resim yüklendikten sonra otomatik olarak küçük resim oluşturmak için bir Storage tetikleyicisi. İşlev, 200×200 piksel boyutunda küçültülmüş bir kopya oluşturur ve thumb_ ön ekiyle orijinal dosyanın yoluna kaydeder. Görüntü işleme, tüm yaygın biçimleri destekleyen ve sistem bağımlılıkları olmadan Node.js ortamında çalışan sharp kitaplığını kullanır.

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

generateThumbnail işlevi, nesnenin Content-Type'ını kontrol eder ve resim olmayanları yok sayarak kaynak tasarrufu sağlar. sharp'ı kullanmak için bağımlılığın package.json'a eklenmesi gerekir. Küçük resim, resmi merkezden 200×200 piksel kareye kırpan fit: “cover” parametresiyle oluşturulur. Oluşturulduktan sonra, küçük resim değiştirilmiş bir adla aynı pakete geri yüklenir.

Genel API için HTTPS Uç Noktası

Üçüncü örnek — sunucu durumunu kontrol etmek için bir REST API uç noktası uygulayan bir HTTPS işlevi. İşlev, bir GET isteğini kabul eder ve projeye bağlı Firebase hizmetlerinin durumu hakkında JSON döndürür. Bu uç nokta, veri göndermeden önce arka uç kullanılabilirliğini doğrulaması gereken izleme ve harici sistemler için kullanışlıdır.

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

api işlevi, yönlendirme için ifade Yönlendirici kullanır ve bu, tek bir işlevde birden çok uç nokta oluştururken kullanışlıdır. Durum denetimi, _health koleksiyonunda Firestore'a yazar ve aynı anda Firestore kullanılabilirliğini doğrulamaya olanak tanır. Üretim için, genel uç noktanın kötüye kullanılmasını önlemek amacıyla bir API anahtarı veya Firebase Auth tokenı aracılığıyla istek kimlik doğrulaması eklenmesi önerilir.

Mobil Uygulamalarda Tipik Kullanım Senaryoları

Cloud Functions en yaygın olarak istemcide yapılamayan veya yapılmaması gereken görevler için kullanılır: push bildirimleri gönderme, yüklenen resimlerin önizlemelerini oluşturma, harici ödeme sistemleriyle entegrasyon, içerik denetleme, Firebase ile üçüncü taraf hizmetler arasında veri senkronizasyonu. Sunucusuz model, bu görevleri uygun maliyetli hale getirir: yalnızca gerçek kod yürütme süresi için ödeme yaparsınız.

Ödeme sistemi entegrasyonu, uygulama içi satın alımları olan uygulamalar için tipik bir senaryodur. Cloud Functions, ödeme sağlayıcısından (Stripe, PayPal) bir webhook alır, istek imzasını doğrular, Firestore'daki abonelik durumunu günceller ve kullanıcıya bir onay gönderir. Tüm kod, istemcide veri kurcalama riski olmadan sunucuda çalışır. Stripe belgelerine (2026) göre, webhook işleme 500 ms'den kısa sürer.

Akıllı içerik denetleme, Google Cloud Vision API aracılığıyla yüklenen resimleri otomatik olarak kontrol etmek için bir Cloud Function Storage tetikleyicisi kullanır. İşlev, güvenli olmayan içeriği (şiddet, yetişkin içeriği) algılamak için resmi Vision API'ye gönderir ve eşik aşılırsa dosyayı siler ve yöneticiyi bilgilendirir. Bu senaryo, kullanıcı galerileri olan UGC uygulamaları için kritiktir.

Veri toplama — Firebase Realtime Database sayaçlarının yerine Cloud Functions. İstemcide bir sayacı okumak ve yazmak yerine (yarış koşullarına yol açar), toplanmış alanların atomik güncellemeleri için bir Firestore onWrite tetikleyicisi kullanın. Örneğin, bir işlev, /posts/{postId}/likes/{userId} alt koleksiyonunda bir belge her eklendiğinde veya kaldırıldığında gönderi beğenilerinin sayısını sayar ve üst belgedeki likesCount alanını günceller.