Firebase Cloud Functions — ano ito, mga trigger at kung paano sumulat ng mga function

Ano ang Firebase Cloud Functions at paano ito nakaayos

Firebase Cloud Functions ay isang computing platform na binuo sa batayan ng Google Cloud Functions (GCF), na inangkop para sa ekosistema ng Firebase. Ang mga function ay karaniwang JavaScript o TypeScript code, na ini-export mula sa module at nirerehistro para sa isang partikular na uri ng event. Kapag nangyari ang event (halimbawa, nagrehistro ang user o nag-upload ng file), pinapatakbo ng Firebase Cloud Functions ang kaukulang code, na ipinapasa dito ang konteksto ng event.

Ang arkitektura ng Cloud Functions ay sumusunod sa prinsipyo ng nag-iisang responsibilidad: isang function ang nagpoproseso ng isang uri ng event at nagsasagawa ng isang atomic na operasyon. Halimbawa, ang function na sendWelcomeEmail ay tinatawag kapag nalikha ang bagong user sa Firebase Authentication at nagpapadala ng welcome letter. Ang ganitong paghihiwalay ay nagpapasimple sa pag-debug, pag-test, at muling paggamit ng mga function sa iba't ibang proyekto.

Bawat function ay tumatakbo sa isang nakahiwalay na container na may pansamantalang lifecycle. Ang maximum na oras ng pagpapatakbo ay 60 segundo bilang default (HTTPS functions — 9 minuto). Kung ang function ay hindi kasya sa time-out, nagtatapos ang kahilingan sa error 500. Para sa mahabang operasyon gamitin ang Cloud Tasks o Pub/Sub na may paulit-ulit na pagsubok. Ang mga container ay maaaring gamitin muli para sa mga susunod na tawag (keep-alive), na nagpapababa ng latency sa mga cold start pagkatapos ng unang tawag.

Kapaligiran ng pagpapatakbo at mga bersyon ng Node.js

Firebase Cloud Functions ay sumusuporta sa ilang bersyon ng Node.js: 18, 20 at 22 (inirerekomenda para sa mga bagong proyekto). Ang pagpili ng bersyon ay itinatakda sa field na engines ng file na package.json. Awtomatikong kino-configure ng Firebase CLI ang kapaligiran ng pagpapatakbo batay sa nakasaad na bersyon. Mahalaga: hindi sinusuportahan ng Firebase Cloud Functions ang pagpapatakbo ng mga arbitraryong Docker container — ang kapaligiran ay mahigpit na itinakda ng Google Cloud Functions.

Para sa mga bagong proyekto ay inirerekomenda ang Node.js 22, dahil kabilang dito ang pinakabagong V8 optimizations, pinabuting trabaho sa ESM modules at WebSocket support sa antas ng platform. Kung ang proyekto ay gumagamit ng mga dependency na pinagsama-sama para sa partikular na bersyon ng Node (halimbawa, native C++ modules), ang compatibility ay dapat suriin nang hiwalay — hindi lahat ng native modules ay nagko-compile sa kapaligiran ng GCF.

Pagkakaiba sa pagitan ng Firebase Cloud Functions at Google Cloud Functions

Firebase Cloud Functions ay isang wrapper sa Google Cloud Functions na may paunang naka-install na Firebase SDK at integrasyon sa mga serbisyo ng Firebase. Sumusulat ang developer ng code gamit ang SDK na firebase-functions, na nagbibigay ng mga naka-type na trigger para sa lahat ng serbisyo ng Firebase. Ang Google Cloud Functions ay isang platform na mas mababang antas, kung saan ang mga trigger ay kino-configure nang malinaw sa pamamagitan ng Eventarc o Pub/Sub.

Pangunahing pagkakaiba: sa Firebase Cloud Functions ang trigger ay nirerehistro nang deklaratibo sa pamamagitan ng tawag na functions.firestore.document('path').onWrite(), at sa Google Cloud Functions — sa pamamagitan ng configuration ng Eventarc na may pag-filter sa mga attribute ng event. Ang Firebase Cloud Functions ay awtomatikong may kasamang Admin SDK, na na-initialize na may mga karapatan ng service account ng proyekto, na nagbibigay ng buong access sa lahat ng serbisyo ng Firebase nang walang karagdagang configuration.

Mga uri ng trigger: anong mga event ang sinusuportahan

Firebase Cloud Functions ay sumusuporta sa 8 kategorya ng mga trigger, na bawat isa ay tumutugma sa partikular na serbisyo ng Firebase o Google Cloud. Ang trigger ay isang kondisyon na kapag naganap ay awtomatikong tinatawag ang function. Hindi direktang pinamamahalaan ng developer ang lifecycle ng function: nirerehistro ng Firebase CLI ang trigger sa Google Cloud Eventarc, at ang cloud platform mismo ang nagpapatakbo ng function kapag naganap ang event.

Ang pinakasikat na mga trigger — mga Firestore trigger: onWrite, onCreate, onUpdate, onDelete. Ang mga ito ay nag-trigger kapag nagbago ang mga dokumento sa mga collection ng Firestore. Nakakatanggap ang function ng mga snapshot ng dokumento bago at pagkatapos ng pagbabago, na nagpapahintulot na ihambing ang mga halaga at tumugon lamang sa mga partikular na pagbabago. Halimbawa, kapag nagbago ang status ng order mula "pending" patungo sa "shipped", maaaring magpadala ng push notification sa user.

Mga Authentication trigger (onCreate, onDelete) ay nag-trigger kapag nalikha o nabura ang account. Ginagamit ang mga ito para sa pag-initialize ng data ng user: paggawa ng dokumento ng user sa Firestore, pagpapadala ng welcome-email, pagsulat sa analytics. Mahalaga: hindi maaaring kanselahin ng function ang paggawa ng user — ito ay tumatakbo pagkatapos na malikha na ang account. Para sa pre-validation gumamit ng mga blocking function (Blocking Functions), na available sa platform na Identity Platform.

Mga HTTPS trigger at CORS

Mga HTTPS function (onRequest) ay nagpapahintulot na lumikha ng mga kumpletong REST API endpoint, na naa-access sa pamamagitan ng HTTP. Hindi tulad ng mga event trigger, ang mga HTTPS function ay tinatawag sa pamamagitan ng URL na may anyong https://{region}-{project}.cloudfunctions.net/{functionName}. Mahalagang i-configure nang tama ang CORS kung ang endpoint ay tinatawag mula sa browser o mobile app. Hindi awtomatikong isinasama ng Firebase SDK ang mga CORS header — kailangang idagdag ang mga ito nang manu-mano sa pamamagitan ng middleware.

Para sa mga mobile client (Android, iOS) hindi kailangan ang CORS, dahil ang mga native HTTP client ay hindi nililimitahan ng Cross-Origin policy. Ang CORS ay may kaugnayan lamang sa mga web request. Kung ang iyong HTTPS function ay tinatawag mula sa parehong app at web, magdagdag ng unibersal na pagproseso ng CORS: res.set('Access-Control-Allow-Origin', '*') para sa development o listahan ng mga pinapayagang domain para sa production.

Pag-iskedyul gamit ang Pub/Sub at Cloud Scheduler

Para sa pana-panahong pagpapatakbo (mga cron task) gamitin ang kombinasyon ng Cloud Scheduler at Pub/Sub. Nagpapadala ang Cloud Scheduler ng mensahe sa Pub/Sub topic ayon sa iskedyul, at ang onPublish trigger ay nagpoproseso ng mensaheng ito. Hindi sinusuportahan ng Firebase CLI ang direktang cron syntax — ang iskedyul ay itinatakda sa pamamagitan ng console ng Google Cloud o Terraform sa format na unix-cron: 0 3 * * * (araw-araw sa 3:00).

Mga halimbawa ng task: araw-araw na pagpapadala, paglilinis ng lumang data, paggawa ng mga ulat, pag-sync sa mga panlabas na API. Mahalaga: ang Cloud Scheduler ay isang bayad na serbisyo ng Google Cloud (mga $2 bawat buwan para sa isang job). Bawat pag-trigger ay itinuturing na hiwalay na tawag ng function at nirerehistro sa mga karaniwang presyo ng Cloud Functions.

Paano sumulat at mag-deploy ng mga function

Ang pag-develop ng Cloud Functions ay nagsisimula sa pag-initialize ng proyekto sa pamamagitan ng Firebase CLI: firebase init functions. Ang command na ito ay lumilikha ng directory na functions/ na may template na index.js (o index.ts), file na package.json at configuration ng TypeScript (kung napili). Pagkatapos ng pag-initialize, sapat na ang sumulat ng function, i-export ito mula sa module, at patakbuhin ang firebase deploy --only functions para sa deploy.

Bawat function ay nirerehistro sa pamamagitan ng tawag sa method ng kaukulang trigger. Halimbawa ng HTTPS function: exports.helloWorld = functions.https.onRequest((req, res) => { res.send("Hello!"); }). Gumagamit ang mga function ng Firebase ng asynchronous na modelo: para sa mga event trigger (hindi HTTPS) dapat magbalik ang function ng Promise. Hinihintay ng Firebase ang pagtatapos ng Promise bago isara ang container. Kung hindi ibinalik ang Promise, maaaring maputol ang function bago matapos ang mga asynchronous na operasyon.

Ang lokal na development ay ginagawa sa pamamagitan ng Firebase Emulator Suite, na kabilang ang emulator ng Cloud Functions. Ang command na firebase emulators:start ay nagpapatakbo ng lokal na server na may mga function, na naa-access sa http://localhost:5001. Sinusuportahan ng emulator ang hot reload kapag nagbago ang code at ganap na nakahiwalay sa production environment, na nagpapahintulot na mag-test ng mga function nang walang panganib na makaapekto sa tunay na data.

Pamamahala ng mga dependency at configuration

Mga dependency ng Cloud Functions ay pinamamahalaan sa pamamagitan ng package.json. Nag-i-install ang Firebase ng production dependencies lamang (dependencies, hindi devDependencies). Ang laki ng package ng function ay nakakaapekto sa oras ng cold start: inirerekomenda na bawasan ang bilang ng mga dependency. Para sa pagtatrabaho sa Firebase Admin SDK, ang dependency na firebase-admin ay naka-install na nang maaga — hindi na ito kailangang idagdag nang manu-mano.

Mga kumpidensyal na data (API keys, tokens) ay hindi dapat itago sa code ng function. Gamitin ang functions.config() para sa pag-iimbak ng configuration: firebase functions:config:set stripe.key="sk_...". Ang mga halaga ay naka-encrypt at available sa runtime sa pamamagitan ng functions.config().stripe.key. Para sa malalaking serialized configuration gamitin ang Secret Manager ng Google Cloud.

Pagproseso ng error at pag-log

Ang pag-log sa Cloud Functions ay ginagawa sa pamamagitan ng console.log, console.warn at console.error. Ang lahat ng log ay awtomatikong kinokolekta sa Google Cloud Logging at available sa console ng Firebase (seksyon Functions > Logs). Para sa structured na pag-log gamitin ang library na winston o pino, na sumusuporta sa JSON formatting at mga antas ng pag-log.

Ang pagproseso ng error ay kritikal para sa reliability: ang hindi naprosesong exception sa Promise ay nagtatapos sa function na may error, pagkatapos ay awtomatikong inuulit ng Firebase ang tawag (retry) na may exponential delay. Ang bilang ng retry ay kino-configure: mula 0 hanggang walang katapusan. Para sa mga event trigger ay inirerekomenda ang pag-activate ng retry upang garantiyahan ang pagproseso ng bawat event kahit sa pansamantalang pagkasira ng mga panlabas na serbisyo.

Cold start at scaling

Cold start ay ang pagkaantala sa unang tawag ng function pagkatapos ng panahon ng kawalan ng aktibidad, kapag ang container na may code ay ni-load at ini-initialize muli. Ayon sa Firebase documentation (2026), ang cold start ay tumatagal mula 200 ms hanggang 2 segundo depende sa laki ng package, bilang ng mga dependency at region. Para sa user interface, ang pagkaantala na higit sa 1 segundo ay kapansin-pansin at maaaring makaapekto sa user experience.

Mga paraan ng pagbawas ng cold start: pagbawas ng mga dependency, paggamit ng TypeScript na may compilation sa CommonJS, pagbawas ng laki ng package ng function, pagtatakda ng minimum na bilang ng mga aktibong instance. Ang Firebase Cloud Functions v2 (2nd gen) ay nagpapahintulot na itakda ang minInstances — minimum na bilang ng mga pinainit na container, na laging handa sa pagproseso ng mga kahilingan. Para sa pag-init ng mga container ay may bayad para sa oras ng idle.

Ang scaling ng Cloud Functions ay awtomatikong nangyayari: kapag tumaas ang bilang ng mga kahilingan, lumilikha ang Firebase ng mga bagong container. Bilang default, ang maximum na bilang ng mga parallel instance ay 3000 (quota ng proyektong Google Cloud). Bawat instance ay nagpoproseso ng isang kahilingan sa isang pagkakataon. Kung mabilis ang function (mas mababa sa 100 ms), ang isang instance ay maaaring magproseso ng hanggang 10 kahilingan bawat segundo, na nagbibigay ng peak throughput hanggang 30 000 kahilingan bawat segundo bawat proyekto.

Configuration ng minInstances at maxInstances

minInstances ay isang parameter na nagre-reserve ng nakasaad na bilang ng mga container at pinapanatili ang mga itong pinainit. Inirerekomenda para sa mga kritikal na HTTPS function, kung saan hindi katanggap-tanggap ang pagkaantala ng cold start. Halimbawa, para sa authentication endpoint itakda ang minInstances: 1. maxInstances ay isang limitasyon sa maximum na bilang ng mga parallel instance, kapaki-pakinabang para maiwasan ang walang kontrol na pagtaas ng gastos sa biglaang pagtaas ng trapiko.

Ang configuration ay ginagawa sa code: functions.runWith({ minInstances: 1, maxInstances: 10 }). Mahalaga: minInstances ay nagpapataas ng gastos, dahil tuloy-tuloy na gumagana ang container. Para sa mga test project ay dapat patayin ang minInstances. Para sa production ay inirerekomenda ang minInstances para sa lahat ng pampublikong HTTPS function at 0 para sa mga event trigger, kung saan ang pagkaantala ng 1 segundo ay hindi kritikal.

Mga region ng deploy

Ang region ng deploy ay nakakaapekto sa latency para sa mga end user at gastos ng papalabas na trapiko. Ang Firebase Cloud Functions ay available sa 30+ region ng Google Cloud. Para sa mga mobile app pumili ng region na pinakamalapit sa iyong target na audience: us-central1 para sa Amerika, europe-west1 para sa Europa, asia-east2 para sa Asya. Hindi mababago ang region pagkatapos ng deploy nang hindi muling i-deploy ang function.

Ang pagpapalit ng region ay ginagawa sa pamamagitan ng parameter na region sa code: functions.region('europe-west1'). Ang lahat ng function sa isang file ay maaaring magkaroon ng iba't ibang region. Para sa mga global na proyekto ay inirerekomenda ang pag-deploy ng mga function sa ilang region at paggamit ng Cloud Load Balancing para sa pamamahagi ng trapiko, bagaman para sa karamihan ng mga mobile app ay sapat ang isang region kung tama ang pagpili.

Mga halimbawa ng code para sa Firebase Cloud Functions

Suriin natin ang mga praktikal na halimbawa ng Cloud Functions sa TypeScript. Gumagamit ang code ng Firebase Functions SDK v2 (2nd gen) na may modular ES syntax. Kabilang sa mga halimbawa ang pagproseso ng event ng paggawa ng user, paggawa ng thumbnail kapag nag-upload ng larawan at simpleng HTTPS endpoint para sa REST API. Lahat ng function ay asynchronous na may pagbabalik ng Promise para sa tamang pagtatapos ng container.

Bago patakbuhin, siguraduhin na na-update ang Firebase CLI sa bersyon 13+: npm install -g firebase-tools. Ang mga v2 function ay nangangailangan ng taripa plan na Blaze. Pag-initialize: firebase init functions na may pagpili ng TypeScript.

Pagproseso ng pagrehistro ng user

Unang halimbawa — paggawa ng dokumento sa Firestore kapag nagrehistro ang bagong user. Ang function ay na-trigger ng event na auth.user().onCreate at sumusulat ng pangunahing profile sa collection na users/{uid}. Ito ay nagpapahintulot na garantiyahan na para sa bawat rehistradong user ay may dokumento na may kinakailangang mga field.

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}`)
    })

Ang function na createUserProfile ay asynchronous — nagbabalik ito ng Promise na hinihintay ng Firebase bago matapos. Kung ang pagsulat sa Firestore ay magtatapos sa error (halimbawa, dahil sa kawalan ng mga karapatan), awtomatikong uulitin ang function (kung aktibo ang retry). Ang field na role na may halagang "free" ay nagpapahintulot na ipatupad ang mga limitasyon ng libreng taripa nang direkta sa Security Rules ng Firestore, sa paghahambing ng resource.data.role sa kinakailangang antas ng access.

Paggawa ng thumbnail kapag nag-upload ng larawan

Ikalawang halimbawa — Storage trigger para sa awtomatikong paggawa ng miniatur (thumbnail) pagkatapos mag-upload ng larawan. Lumilikha ang function ng pinaliit na kopya na may sukat na 200x200 pixels at iniimbak ito sa landas ng orihinal na file na may prefix na thumb_. Para sa pagproseso ng mga larawan ginagamit ang library na sharp, na sumusuporta sa lahat ng karaniwang format at gumagana sa kapaligiran ng Node.js nang walang mga system dependency.

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 })
    })

Ang function na generateThumbnail ay sumusuri sa Content-Type ng object at binabalewala ang mga hindi-larawan, na nakakatipid ng resources. Para sa pagtatrabaho sa sharp, ang dependency ay dapat idagdag sa package.json. Ang thumbnail ay nalikha na may parameter na fit: "cover", na pinuputol ang larawan sa gitna hanggang sa parisukat na 200x200 pixels. Pagkatapos ng paggawa, ang thumbnail ay ina-upload pabalik sa parehong bucket na may binagong pangalan.

HTTPS endpoint para sa pampublikong API

Ikatlong halimbawa — HTTPS function na nagpapatupad ng REST API endpoint para sa pag-check ng status ng server. Ang function ay tumatanggap ng GET request at nagbabalik ng JSON na may impormasyon tungkol sa estado ng mga serbisyo ng Firebase na konektado sa proyekto. Kapaki-pakinabang ang endpoint para sa monitoring at para sa mga panlabas na system na kailangang suriin ang availability ng backend bago magpadala ng data.

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)

Ang function na api ay gumagamit ng express Router para sa routing, na maginhawa kapag lumilikha ng ilang endpoint sa isang function. Ang health check ay isinusulat sa Firestore sa collection na _health, na nagpapahintulot na sabay na suriin ang availability ng Firestore. Para sa production ay inirerekomenda ang pagdagdag ng authentication ng kahilingan sa pamamagitan ng API key o Firebase Auth token, upang maiwasan ang pang-aabuso sa pampublikong endpoint.

Mga karaniwang sitwasyon ng paggamit sa mga mobile app

Cloud Functions ay madalas na ginagamit para sa mga task na hindi posible o hindi kanais-nais na gawin sa client: pagpapadala ng push notification, paggawa ng preview ng mga na-upload na larawan, integrasyon sa mga panlabas na payment system, moderasyon ng content, pag-sync ng data sa pagitan ng Firebase at mga serbisyo ng ikatlong partido. Ginagawang matipid ng serverless na modelo ang mga task na ito: ang bayad ay sinisingil lamang para sa aktwal na oras ng pagpapatakbo ng code.

Integrasyon sa mga payment system — karaniwang sitwasyon para sa mga app na may in-app na pagbili. Nakakatanggap ang Cloud Functions ng webhook mula sa payment provider (Stripe, PayPal), sinusuri ang lagda ng kahilingan, ina-update ang status ng subscription sa Firestore at nagpapadala ng kumpirmasyon sa user. Ang buong code ay tumatakbo sa server nang walang panganib ng pagpapalit ng data sa client. Ayon sa Stripe documentation (2026), ang pagproseso ng webhook ay tumatagal ng mas mababa sa 500 ms.

Matalinong moderasyon ng content ay gumagamit ng Storage trigger ng Cloud Functions para sa awtomatikong pag-check ng mga na-upload na larawan sa pamamagitan ng Google Cloud Vision API. Ipinapadala ng function ang larawan sa Vision API para sa detekyon ng hindi ligtas na content (karahasan, content para sa mga matatanda) at, kung nalampasan ang threshold, buburahin ang file at aabisuhan ang administrator. Kritikal ang sitwasyong ito para sa mga UGC app na may mga gallery ng user.

Agregasyon ng data — Cloud Functions bilang kapalit ng mga counter ng Firebase Realtime Database. Sa halip na basahin at isulat ang counter sa client (na humahantong sa race conditions), gamitin ang Firestore trigger na onWrite para sa atomic na pag-update ng mga pinagsamang field. Halimbawa, kinukuwenta ng function ang bilang ng likes ng post sa bawat pagdagdag o pagbura ng dokumento sa subcollection na /posts/{postId}/likes/{userId} at ina-update ang field na likesCount sa parent na dokumento.