Firebase Cloud Functions — nədir, trigerlər və funksiyaları necə yazmaq olar

Firebase Cloud Functions nədir və necə qurulub

Firebase Cloud Functions — Google Cloud Functions (GCF) bazasında qurulmuş, Firebase ekosistemi üçün uyğunlaşdırılmış hesablama platformasıdır. Funksiyalar moduldan ixrac edilən və müəyyən hadisə növünə qeydiyyatdan keçirilən adi JavaScript və ya TypeScript kodunu təmsil edir. Hadisə baş verdikdə (məsələn, istifadəçi qeydiyyatdan keçir və ya fayl yükləyir), Firebase Cloud Functions müvafiq kodu işə salır və ona hadisə kontekstini ötürür.

Cloud Functions arxitekturası tək məsuliyyət prinsipinə əməl edir: bir funksiya bir növ hadisəni emal edir və bir atomik əməliyyat yerinə yetirir. Məsələn, sendWelcomeEmail funksiyası Firebase Authentication-da yeni istifadəçi yaradıldıqda çağırılır və xoş gəldiniz məktubu göndərir. Belə izolyasiya funksiyaların debug edilməsini, test edilməsini və müxtəlif layihələrdə yenidən istifadəsini sadələşdirir.

Hər bir funksiya müvəqqəti həyat dövrü olan izolyasiya olunmuş konteynerdə icra olunur. Maksimal icra müddəti standart olaraq 60 saniyədir (HTTPS funksiyaları — 9 dəqiqə). Funksiya vaxt limitinə sığmırsa, sorğu 500 xətası ilə bitir. Uzun əməliyyatlar üçün Cloud Tasks və ya təkrar cəhdləri olan Pub/Sub istifadə edin. Konteynerlər sonrakı çağırışlar üçün yenidən istifadə oluna bilər (keep-alive), bu da ilk çağırışdan sonra soyuq startlarda gecikməni azaldır.

İcra mühiti və Node.js versiyaları

Firebase Cloud Functions bir neçə Node.js versiyasını dəstəkləyir: 18, 20 və 22 (yeni layihələr üçün tövsiyə olunur). Versiya seçimi package.json faylının engines sahəsində təyin edilir. Firebase CLI göstərilən versiya əsasında icra mühitini avtomatik konfiqurasiya edir. Vacib: Firebase Cloud Functions ixtiyari Docker konteynerlərinin işə salınmasını dəstəkləmir — mühit Google Cloud Functions tərəfindən ciddi şəkildə müəyyən edilib.

Yeni layihələr üçün Node.js 22 tövsiyə olunur, çünki o, ən son V8 optimallaşdırmalarını, ESM modulları ilə təkmilləşdirilmiş işi və platforma səviyyəsində WebSocket dəstəyini əhatə edir. Layihə müəyyən Node versiyası üçün yığılmış asılılıqlardan istifadə edirsə (məsələn, C++ native modulları), uyğunluğu ayrıca yoxlamaq lazımdır — bütün native modullar GCF mühitində kompilyasiya olunmur.

Firebase Cloud Functions və Google Cloud Functions arasındakı fərq

Firebase Cloud Functions — əvvəlcədən quraşdırılmış Firebase SDK və Firebase xidmətləri ilə inteqrasiyası olan Google Cloud Functions üzərindəki qabıqdır. Tərtibatçı bütün Firebase xidmətləri üçün tipli trigerlər təqdim edən firebase-functions SDK-dan istifadə edərək kod yazır. Google Cloud Functions — trigerlərin Eventarc və ya Pub/Sub vasitəsilə açıq şəkildə konfiqurasiya olunduğu daha aşağı səviyyəli platformadır.

Əsas fərq: Firebase Cloud Functions-da trigger functions.firestore.document('path').onWrite() çağırışı ilə deklarativ şəkildə qeydiyyatdan keçirilir, Google Cloud Functions-da isə — hadisə atributları üzrə filtrləmə ilə Eventarc konfiqurasiyası vasitəsilə. Firebase Cloud Functions həmçinin layihənin xidmət hesabının hüquqları ilə işə salınmış Admin SDK ilə avtomatik gəlir ki, bu da əlavə konfiqurasiya olmadan bütün Firebase xidmətlərinə tam giriş verir.

Triger növləri: hansı hadisələr dəstəklənir

Firebase Cloud Functions 8 kateqoriya triggeri dəstəkləyir, onların hər biri müəyyən Firebase və ya Google Cloud xidmətinə uyğundur. Trigger — baş verdikdə funksiyanın avtomatik çağırıldığı şərtdir. Tərtibatçı funksiyanın həyat dövrünü birbaşa idarə etmir: Firebase CLI triggeri Google Cloud Eventarc-da qeydiyyatdan keçirir və bulud platforması hadisə baş verdikdə funksiyanı özü işə salır.

Ən populyar trigerlər — Firestore trigerləri: onWrite, onCreate, onUpdate, onDelete. Onlar Firestore kolleksiyalarındakı sənədlər dəyişdikdə işə düşür. Funksiya dəyişiklikdən əvvəlki və sonrakı sənəd anlıq görüntülərini alır ki, bu da dəyərləri müqayisə etməyə və yalnız müəyyən dəyişikliklərə reaksiya verməyə imkan verir. Məsələn, sifarişin statusu "pending"-dən "shipped"-ə dəyişdikdə istifadəçiyə push bildirişi göndərilə bilər.

Authentication trigerləri (onCreate, onDelete) hesab yaradıldıqda və ya silindikdə işə düşür. Onlar istifadəçi məlumatlarının işə salınması üçün istifadə olunur: Firestore-da istifadəçi sənədinin yaradılması, xoş gəldiniz e-poçtunun göndərilməsi, analitikaya yazılması. Vacib: funksiya istifadəçinin yaradılmasını ləğv edə bilməz — o, hesab artıq yaradıldıqdan sonra icra olunur. İlkin yoxlama üçün Identity Platform-da mövcud olan bloklayan funksiyalardan (Blocking Functions) istifadə edin.

HTTPS trigerləri və CORS

HTTPS funksiyaları (onRequest) HTTP vasitəsilə əlçatan tam hüquqlu REST API endpointləri yaratmağa imkan verir. Hadisə trigerlərindən fərqli olaraq, HTTPS funksiyaları https://{region}-{project}.cloudfunctions.net/{functionName} formasındakı URL vasitəsilə çağırılır. Endpoint brauzerdən və ya mobil tətbiqdən çağırılırsa, CORS-u düzgün konfiqurasiya etmək vacibdir. Firebase SDK CORS başlıqlarını avtomatik əlavə etmir — onları middleware vasitəsilə əl ilə əlavə etmək lazımdır.

Mobil müştərilər (Android, iOS) üçün CORS tələb olunmur, çünki native HTTP müştəriləri Cross-Origin siyasəti ilə məhdudlaşmır. CORS yalnız veb sorğuları üçün aktualdır. HTTPS funksiyanız həm tətbiqdən, həm də vebdən çağırılırsa, universal CORS emalı əlavə edin: development üçün res.set('Access-Control-Allow-Origin', '*') və ya production üçün icazə verilən domenlər siyahısı.

Pub/Sub və Cloud Scheduler ilə planlaşdırma

Dövri icra üçün (cron tapşırıqları) Cloud Scheduler və Pub/Sub kombinasiyasından istifadə edin. Cloud Scheduler cədvələ uyğun olaraq Pub/Sub topic-inə mesaj göndərir, onPublish triggeri isə bu mesajı emal edir. Firebase CLI birbaşa cron sintaksisini dəstəkləmir — cədvəl Google Cloud konsolu və ya Terraform vasitəsilə unix-cron formatında təyin edilir: 0 3 * * * (hər gün 3:00-da).

Tapşırıq nümunələri: gündəlik göndəriş, köhnəlmiş məlumatların təmizlənməsi, hesabatların yaradılması, xarici API-lərlə sinxronlaşdırma. Vacib: Cloud Scheduler — Google Cloud-un ödənişli xidmətidir (bir job üçün ayda təxminən $2). Hər işə düşmə funksiyanın ayrıca çağırışı sayılır və Cloud Functions standart qiymətləri ilə tarifləndirilir.

Funksiyaları necə yazmaq və yerləşdirmək olar

Cloud Functions inkişafı Firebase CLI vasitəsilə layihənin işə salınması ilə başlayır: firebase init functions. Bu əmr index.js (və ya index.ts) şablonu, package.json faylı və TypeScript konfiqurasiyası (seçilmişsə) olan functions/ kataloqunu yaradır. İşə salındıqdan sonra funksiyanı yazmaq, moduldan ixrac etmək və yerləşdirmək üçün firebase deploy --only functions icra etmək kifayətdir.

Hər bir funksiya müvafiq triggerin metodunun çağırışı vasitəsilə qeydiyyatdan keçirilir. HTTPS funksiyası nümunəsi: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Firebase funksiyaları asinxron modeldən istifadə edir: hadisə trigerləri üçün (HTTPS deyil) funksiya Promise qaytarmalıdır. Firebase konteyneri bağlamadan əvvəl Promise-in tamamlanmasını gözləyir. Promise qaytarılmırsa, funksiya asinxron əməliyyatlar tamamlanmadan kəsilə bilər.

Lokal inkişaf Cloud Functions emulyatorunu özündə birləşdirən Firebase Emulator Suite vasitəsilə aparılır. firebase emulators:start əmri funksiyaları olan lokal serveri işə salır, o http://localhost:5001 ünvanında əlçatandır. Emulyator kod dəyişdikdə hot reload (isti yenidən yükləmə) dəstəkləyir və production mühitindən tam izolyasiya olunub ki, bu da funksiyaları real məlumatlara təsir riski olmadan test etməyə imkan verir.

Asılılıqların və konfiqurasiyanın idarə edilməsi

Asılılıqlar Cloud Functions package.json vasitəsilə idarə olunur. Firebase yalnız production asılılıqlarını (devDependencies deyil, dependencies) quraşdırır. Funksiya paketinin ölçüsü soyuq start vaxtına təsir edir: asılılıqların sayını minimuma endirmək tövsiyə olunur. Firebase Admin SDK ilə iş üçün firebase-admin asılılığı artıq əvvəlcədən quraşdırılıb — onu əl ilə əlavə etməyə ehtiyac yoxdur.

Məxfi məlumatlar (API açarları, tokenlər) funksiya kodunda saxlanılmamalıdır. Konfiqurasiyanı saxlamaq üçün functions.config() istifadə edin: firebase functions:config:set stripe.key="sk_...". Dəyərlər şifrələnir və runtime-də functions.config().stripe.key vasitəsilə əlçatandır. Böyük həcmli seriyalaşdırılmış konfiqurasiyalar üçün Google Cloud Secret Manager istifadə edin.

Xəta emalı və loqlama

Loqlama Cloud Functions-da console.log, console.warn və console.error vasitəsilə həyata keçirilir. Bütün loqlar avtomatik olaraq Google Cloud Logging-də toplanır və Firebase konsolunda (Functions > Logs bölməsi) əlçatandır. Strukturlaşdırılmış loqlama üçün JSON formatlaşdırmanı və loqlama səviyyələrini dəstəkləyən winston və ya pino kitabxanasından istifadə edin.

Xəta emalı etibarlılıq üçün kritik əhəmiyyətlidir: Promise-də emal olunmayan istisna funksiyanı xəta ilə bitirir, bundan sonra Firebase eksponensial gecikmə ilə çağırışı avtomatik təkrarlayır (retry). Retry sayı konfiqurasiya olunur: 0-dan sonsuza qədər. Hadisə trigerləri üçün xarici xidmətlərin müvəqqəti nasazlıqlarında belə hər hadisənin emalını təmin etmək üçün retry-i aktivləşdirmək tövsiyə olunur.

Soyuq start və miqyaslama

Soyuq start (cold start) — kodlu konteynerin yenidən yüklənib işə salındığı hərəkətsizlik dövründən sonra funksiyanın ilk çağırışındakı gecikmədir. Firebase documentation (2026) məlumatlarına görə, soyuq start paketin ölçüsündən, asılılıqların sayından və regiondan asılı olaraq 200 ms-dən 2 saniyəyə qədər çəkir. İstifadəçi interfeysi üçün 1 saniyədən artıq gecikmə hiss olunur və user experience-ə təsir edə bilər.

Soyuq startı minimuma endirmə yolları: asılılıqların minimallaşdırılması, CommonJS-ə kompilyasiya ilə TypeScript istifadəsi, funksiya paketinin ölçüsünün azaldılması, aktiv instansların minimum sayının təyin edilməsi. Firebase Cloud Functions v2 (2nd gen) minInstances — sorğuları emal etməyə həmişə hazır olan qızdırılmış konteynerlərin minimum sayını təyin etməyə imkan verir. Konteynerlərin qızdırılması üçün boş dayanma vaxtına görə ödəniş alınır.

Miqyaslama Cloud Functions-da avtomatik baş verir: sorğuların sayı artdıqda Firebase yeni konteynerlər yaradır. Standart olaraq paralel instansların maksimal sayı 3000-dir (Google Cloud layihə kvotası). Hər instans eyni anda bir sorğunu emal edir. Funksiya sürətlidirsə (100 ms-dən az), bir instans saniyədə 10 sorğuya qədər emal edə bilər ki, bu da layihə üzrə saniyədə 30 000 sorğuya qədər pik ötürmə qabiliyyəti verir.

minInstances və maxInstances konfiqurasiyası

minInstances — göstərilən sayda konteyneri rezerv edən və onları qızdırılmış saxlayan parametrdir. Soyuq start gecikməsinin yolverilməz olduğu kritik HTTPS funksiyaları üçün tövsiyə olunur. Məsələn, autentifikasiya endpointi üçün minInstances: 1 təyin edin. maxInstances — trafikin qəfil artmasında xərclərin nəzarətsiz artmasının qarşısını almaq üçün faydalı olan paralel instansların maksimal sayı məhdudiyyətidir.

Konfiqurasiya kodda aparılır: functions.runWith({ minInstances: 1, maxInstances: 10 }). Vacib: minInstances xərci artırır, çünki konteyner fasiləsiz işləyir. Test layihələri üçün minInstances-ı söndürmək lazımdır. Production üçün bütün açıq HTTPS funksiyalarında minInstances, hadisə trigerləri üçün isə 0 tövsiyə olunur, çünki orada 1 saniyəlik gecikmə kritik deyil.

Yerləşdirmə regionları

Yerləşdirmə regionu son istifadəçilərə gecikməyə və gedən trafikin qiymətinə təsir edir. Firebase Cloud Functions 30+ Google Cloud regionunda mövcuddur. Mobil tətbiqlər üçün hədəf auditoriyanıza ən yaxın regionu seçin: Amerika üçün us-central1, Avropa üçün europe-west1, Asiya üçün asia-east2. Region funksiyanı yenidən yerləşdirmədən deplydan sonra dəyişdirilə bilməz.

Regionun dəyişdirilməsi kodda region parametri vasitəsilə aparılır: functions.region('europe-west1'). Bir fayldakı bütün funksiyalar müxtəlif regionlara malik ola bilər. Qlobal layihələr üçün funksiyaları bir neçə regionda yerləşdirmək və trafiki paylamaq üçün Cloud Load Balancing istifadə etmək tövsiyə olunur, baxmayaraq ki, əksər mobil tətbiqlər üçün düzgün seçim şərtilə bir region kifayətdir.

Firebase Cloud Functions üçün kod nümunələri

TypeScript-də Cloud Functions-ın praktiki nümunələrini nəzərdən keçirək. Kod ES modul sintaksisi ilə Firebase Functions SDK v2 (2nd gen) istifadə edir. Nümunələrə istifadəçinin yaradılması hadisəsinin emalı, şəkil yüklənərkən thumbnail yaradılması və REST API üçün sadə HTTPS endpointi daxildir. Bütün funksiyalar konteynerin düzgün tamamlanması üçün Promise qaytarmaqla asinxrondur.

İşə salmazdan əvvəl Firebase CLI-nin 13+ versiyasına yeniləndiyinə əmin olun: npm install -g firebase-tools. v2 funksiyaları Blaze tarif planını tələb edir. İşə salma: TypeScript seçimi ilə firebase init functions.

İstifadəçinin qeydiyyatının emalı

Birinci nümunə — yeni istifadəçi qeydiyyatdan keçəndə Firestore-da sənədin yaradılmasıdır. Funksiya auth.user().onCreate hadisəsi ilə işə düşür və users/{uid} kolleksiyasına əsas profili yazır. Bu, hər qeydiyyatdan keçmiş istifadəçi üçün lazımi sahələri olan sənədin mövcudluğunu təmin etməyə imkan verir.

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 funksiyası asinxrondur — Firebase-in tamamlanmadan əvvəl gözlədiyi Promise-i qaytarır. Firestore-a yazı xəta ilə bitsə (məsələn, hüquqların olmaması səbəbindən), funksiya avtomatik təkrarlanacaq (retry aktivdirsə). "free" dəyəri olan role sahəsi pulsuz tarif məhdudiyyətlərini birbaşa Firestore Security Rules-da həyata keçirməyə imkan verir: resource.data.role tələb olunan giriş səviyyəsi ilə müqayisə olunur.

Şəkil yüklənərkən thumbnail yaradılması

İkinci nümunə — şəkil yükləndikdən sonra avtomatik miniatür (thumbnail) yaratmaq üçün Storage triggeridir. Funksiya 200x200 piksel ölçüsündə kiçildilmiş nüsxə yaradır və onu thumb_ prefiksi ilə mənbə faylının yolunda saxlayır. Şəkillərin emalı üçün bütün geniş yayılmış formatları dəstəkləyən və sistem asılılıqları olmadan Node.js mühitində işləyən sharp kitabxanası istifadə olunur.

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 funksiyası obyektin Content-Type-ni yoxlayır və şəkil olmayanları görməməzliyə verir ki, bu da resurslara qənaət edir. sharp ilə iş üçün asılılıq package.json-a əlavə edilməlidir. Thumbnail şəkli mərkəzdə 200x200 piksel kvadratına kəsən fit: "cover" parametri ilə yaradılır. Yaradıldıqdan sonra thumbnail dəyişdirilmiş adla eyni bucket-ə geri yüklənir.

Açıq API üçün HTTPS endpointi

Üçüncü nümunə — server statusunu yoxlamaq üçün REST API endpointini reallaşdıran HTTPS funksiyasıdır. Funksiya GET sorğusunu qəbul edir və layihəyə qoşulmuş Firebase xidmətlərinin vəziyyəti haqqında məlumatla JSON qaytarır. Endpoint monitoring üçün və məlumat göndərməzdən əvvəl backend-in əlçatanlığını yoxlamalı olan xarici sistemlər üçün faydalı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 funksiyası marşrutlaşdırma üçün express Router istifadə edir ki, bu da bir funksiyada bir neçə endpoint yaratarkən rahatdır. Health check Firestore-da _health kolleksiyasına yazılır ki, bu da eyni vaxtda Firestore-un əlçatanlığını yoxlamağa imkan verir. Production üçün açıq endpointdən sui-istifadənin qarşısını almaq üçün API açarı və ya Firebase Auth tokeni vasitəsilə sorğu autentifikasiyası əlavə etmək tövsiyə olunur.

Mobil tətbiqlərdə tipik istifadə ssenariləri

Cloud Functions ən çox müştəri tərəfdə yerinə yetirilməsi mümkün olmayan və ya arzuolunmaz olan tapşırıqlar üçün istifadə olunur: push bildirişlərinin göndərilməsi, yüklənmiş şəkillərin önizləməsinin yaradılması, xarici ödəniş sistemləri ilə inteqrasiya, məzmun moderasiyası, Firebase və üçüncü tərəf xidmətləri arasında məlumat sinxronlaşdırılması. Serverlərsiz model bu tapşırıqları qənaətcil edir: ödəniş yalnız kodun faktiki icra vaxtı üçün alınır.

Ödəniş sistemləri ilə inteqrasiya — in-app alışları olan tətbiqlər üçün tipik ssenaridir. Cloud Functions ödəniş provayderindən (Stripe, PayPal) webhook alır, sorğunun imzasını yoxlayır, Firestore-da abunə statusunu yeniləyir və istifadəçiyə təsdiqləmə göndərir. Bütün kod serverdə icra olunur və müştəri tərəfdə məlumatların əvəzlənməsi riski yoxdur. Stripe documentation (2026) məlumatlarına görə, webhook emalı 500 ms-dən az çəkir.

Ağıllı məzmun moderasiyası yüklənmiş şəkillərin Google Cloud Vision API vasitəsilə avtomatik yoxlanması üçün Storage triggerindən istifadə edir. Funksiya təhlükəli məzmunun (zorakılıq, böyüklər üçün məzmun) aşkarlanması üçün şəkli Vision API-yə göndərir və hədd aşılıbsa, faylı silir və administratora bildirir. Bu ssenari istifadəçi qalereyaları olan UGC tətbiqləri üçün kritik əhəmiyyətlidir.

Məlumat aqreqasiyası — Cloud Functions Firebase Realtime Database sayğaclarının əvəzedicisi kimi. Sayğacın müştəri tərəfdə oxunması və yazılması əvəzinə (bu, race conditions-a gətirib çıxarır), aqreqasiya olunmuş sahələrin atomik yenilənməsi üçün Firestore onWrite triggerindən istifadə edin. Məsələn, funksiya /posts/{postId}/likes/{userId} altkolleksiyasında sənəd əlavə ediləndə və ya silinəndə postun bəyənmə sayını hesablayır və ana sənəddə likesCount sahəsini yeniləyir.