1. nesil Node.js işlevlerini 2. nesle yükseltme

1. nesil işlevleri kullanan uygulamalar, bu kılavuzdaki talimatları uygulayarak 2. nesil işlevlere geçmeyi düşünebilir. 2. nesil işlevler, daha iyi performans, daha iyi yapılandırma, daha iyi izleme ve daha fazlasını sağlamak için Cloud Run kullanır.

Bu belgedeki örneklerde, CommonJS modülleri (require stilinde içe aktarmalar) ile JavaScript kullandığınız varsayılır. Ancak aynı ilkeler, ESM (import … from stilinde içe aktarmalar) ile JavaScript ve TypeScript için de geçerlidir.

Taşıma süreci

1. nesil ve 2. nesil işlevler, aynı kaynak dosyasında yan yana bulunabilir. Bu sayede, kod tabanınızı hazır olduğunuzda parça parça taşıyabilirsiniz. Ancak bu paketlerin karıştırılmasının tek bir ayrı fonksiyon içinde çalışmadığını unutmayın.

Devam etmeden önce her seferinde bir işlevi taşımanızı, test ve doğrulama işlemlerini gerçekleştirmenizi öneririz.

Firebase CLI ve firebase-functions sürümlerini doğrulama

En az Firebase CLI sürümü 12.00 ve firebase-functions sürümü 4.3.0 kullandığınızdan emin olun. Daha yeni sürümler hem 1. hem de 2. nesil cihazları destekleyecektir.

İçe aktarma işlemlerini güncelleme

2. nesil işlevler, firebase-functions SDK'sındaki v2 alt paketinden içe aktarılır. Bu farklı içe aktarma yolu, Firebase CLI'nın işlev kodunuzu 1. veya 2. nesil işlev olarak dağıtıp dağıtmayacağını belirlemek için gereken tek şeydir.

v2 alt paketi modülerdir ve yalnızca ihtiyacınız olan belirli modülü içe aktarmanızı öneririz.

Önce: 1. nesil

const functions = require("firebase-functions/v1");

Sonra: 2. nesil

// explicitly import each trigger
const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

Tetikleyici tanımlarını güncelleme

2. nesil SDK, modüler içe aktarmaları tercih ettiğinden tetikleyici tanımlarını önceki adımdaki değişen içe aktarmaları yansıtacak şekilde güncelleyin.

Bazı tetikleyiciler için geri çağırma işlevlerine iletilen bağımsız değişkenler değişti. Bu örnekte, onDocumentCreated geri çağırma işlevinin bağımsız değişkenlerinin tek bir event nesnesinde birleştirildiğini unutmayın. Ayrıca, bazı tetikleyicilerde onRequest tetikleyicisinin cors seçeneği gibi kullanışlı yeni yapılandırma özellikleri bulunur.

Önce: 1. nesil

const functions = require("firebase-functions/v1");

exports.date = functions.https.onRequest((req, res) => {
  // ...
});

exports.uppercase = functions.firestore
  .document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

Sonra: 2. nesil

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");

exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

JavaScript ile yapı bozma sayesinde yeniden yazma çabalarını en aza indirme

İşlevleriniz, 1. nesil bağlam veya sağlayıcıya özel parametreler (ör. message veya snapshot) kullanan karmaşık gövdelere sahipse 2. nesil SDK'ya yerleştirilmiş 1. nesil uyumluluk yardımcılarını kullanabilirsiniz.

2. nesil SDK, etkinlik nesnesini 1. nesil imzalarıyla eşleşen alıcılarla otomatik olarak yamalar. Bu sayede, işlev mantığınızı yeniden yazma ihtiyacını en aza indirerek bu özellikleri doğrudan işleyici imzasında ayıklamak için JavaScript destructuring'i kullanabilirsiniz.

Sağlayıcı eşleme referansı

Sağlayıcı 1. nesil bağımsız değişkenler 2. nesil düzeltilmiş etkinlik ayrıştırma
Pub/Sub (message, context) ({ message, context }) => { ... }
Cloud Firestore (snapshot, context) ({ snapshot, context }) => { ... }
Cloud Storage (object, context) ({ object, context }) => { ... }
Realtime Database (snapshot, context) ({ snapshot, context }) => { ... }
Remote Config (version, context) ({ version, context }) => { ... }
Cloud Scheduler (context) ({ context }) => { ... }
Görev Sırası (data, context) ({ data, context }) => { ... }

Önce (1. nesil):

export const myPubSubV1 = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  const data = message.json;
  const eventId = context.eventId;
  // ... rest of the logic
});

Yeni Alternatif (2. nesil, Destructuring ile):

import { onMessagePublished } from "firebase-functions/v2/pubsub";

export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
  // No need to change the function body!
  const data = message.json;      // Uses v1 Message wrapper
  const eventId = context.eventId; // Uses v1 EventContext map
  // ... rest of the logic
});

Parametre haline getirilmiş yapılandırmayı kullanma

2. nesil işlevler, kod tabanınızda yapılandırma parametrelerini bildirimsel olarak tanımlamak için daha güvenli bir arayüz sunmak amacıyla functions.config desteğini bırakıyor. Yeni params modülüyle, tüm parametreler geçerli bir değere sahip olmadığı sürece CLI dağıtımı engeller. Böylece, bir işlevin eksik yapılandırmayla dağıtılmaması sağlanır.

Önce: 1. nesil

const functions = require("firebase-functions/v1");

exports.getQuote = functions.https.onRequest(async (req, res) => {
  const quote = await fetchMotivationalQuote(functions.config().apiKey);
  // ...
});

Sonra: 2. nesil

const {onRequest} = require("firebase-functions/v2/https");
const {defineSecret} = require("firebase-functions/params");

// Define the secret parameter
const apiKey = defineSecret("API_KEY");

exports.getQuote = onRequest(
  // make the secret available to this function
  { secrets: [apiKey] },
  async (req, res) => {
    // retrieve the value of the secret
    const quote = await fetchMotivationalQuote(apiKey.value());
    // ...
  }
);

functions.config ile mevcut bir ortam yapılandırmanız varsa 2. nesle yükseltme işleminizin bir parçası olarak bu yapılandırmayı taşıyın.

functions.config API'sı kullanımdan kaldırıldı ve Mart 2027'de devre dışı bırakılacak. Bu tarihten sonra functions.config içeren dağıtımlar başarısız olur.

Dağıtım hatalarını önlemek için yapılandırmanızı Firebase KSA'yı kullanarak Cloud Secret Manager'a taşıyın. Bu, yapılandırmanızı taşımanın en verimli ve güvenli yolu olduğundan önemle tavsiye edilir.

  1. Firebase CLI ile yapılandırmayı dışa aktarma

    Mevcut ortam yapılandırmanızı Cloud Secret Manager'da yeni bir sır olarak dışa aktarmak için config export komutunu kullanın:

    $ firebase functions:config:export
i  This command retrieves your Runtime Config values (accessed via functions.config())
   and exports them as a Secret Manager secret.

i  Fetching your existing functions.config() from your project...  ✔
   Fetched your existing functions.config().

i  Configuration to be exported:
⚠  This may contain sensitive data. Do not share this output.

{
   ...
}

✔ What would you like to name the new secret for your configuration? RUNTIME_CONFIG

✔  Created new secret version projects/project/secrets/RUNTIME_CONFIG/versions/1```

  2. Gizli bilgileri bağlamak için işlev kodunu güncelleme

    Cloud Secret Manager'daki yeni gizli dizide depolanan yapılandırmayı kullanmak için işlev kaynağınızda defineJsonSecret API'sini kullanın. Ayrıca, gizli anahtarların ihtiyaç duyulan tüm işlevlere bağlı olduğundan emin olun.

    Önce

    const functions = require("firebase-functions/v1");

exports.myFunction = functions.https.onRequest((req, res) => {
  const apiKey = functions.config().someapi.key;
  // ...
});

    Sonra

    const { onRequest } = require("firebase-functions/v2/https");
const { defineJsonSecret } = require("firebase-functions/params");

const config = defineJsonSecret("RUNTIME_CONFIG");

exports.myFunction = onRequest(
  // Bind secret to your function
  { secrets: [config] },
  (req, res) => {
    // Access secret values via .value()
    const apiKey = config.value().someapi.key;
    // ...
});

  3. İşlevleri dağıtma

    Değişiklikleri uygulamak ve gizli izinleri bağlamak için güncellenen işlevlerinizi dağıtın.

    firebase deploy --only functions:<your-function-name>

Çalışma zamanı seçeneklerini ayarlama

Çalışma zamanı seçeneklerinin yapılandırılması 1. ve 2. nesil arasında değişti. 2. nesilde ayrıca tüm işlevler için seçenekleri ayarlama özelliği de eklendi.

Önce: 1. nesil

const functions = require("firebase-functions/v1");

exports.date = functions
  .runWith({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  })
  // locate function closest to users
  .region("asia-northeast1")
  .https.onRequest((req, res) => {
    // ...
  });

exports.uppercase = functions
  // locate function closest to users and database
  .region("asia-northeast1")
  .firestore.document("my-collection/{docId}")
  .onCreate((change, context) => {
    // ...
  });

Sonra: 2. nesil

const {onRequest} = require("firebase-functions/v2/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions/v2");

// locate all functions closest to users
setGlobalOptions({ region: "asia-northeast1" });

exports.date = onRequest({
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  }, (req, res) => {
  // ...
});

exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  /* ... */
});

Varsayılan hizmet hesabını güncelleme (isteğe bağlı)

1. nesil işlevler, Firebase API'lerine erişimi yetkilendirmek için Google App Engine varsayılan hizmet hesabını kullanırken 2. nesil işlevler Compute Engine varsayılan hizmet hesabını kullanır. Bu fark, 1. nesil hizmet hesabına özel izinler verdiğiniz durumlarda 2. nesile taşınan işlevlerle ilgili izin sorunlarına yol açabilir. Herhangi bir hizmet hesabı iznini değiştirmediyseniz bu adımı atlayabilirsiniz.

Önerilen çözüm, 2. nesil varsayılanını geçersiz kılarak mevcut 1. nesil App Engine varsayılan hizmet hesabını 2. nesile taşımak istediğiniz işlevlere açıkça atamaktır. Bunu, taşınan her işlevin serviceAccountEmail için doğru değeri ayarladığından emin olarak yapabilirsiniz:

const {onRequest} = require("firebase-functions/https");
const {onDocumentCreated} = require("firebase-functions/v2/firestore");
const {setGlobalOptions} = require("firebase-functions");

// Use the App Engine default service account for all functions
setGlobalOptions({serviceAccountEmail: '<my-project-number>@<wbr>appspot.gserviceaccount.com'});

// Now I use the App Engine default service account.
exports.date = onRequest({cors: true}, (req, res) => {
  // ...
});

// I do too!
exports.uppercase = onDocumentCreated("my-collection/{docId}", (event) => {
  // ...
});

Alternatif olarak, hizmet hesabı ayrıntılarını hem App Engine varsayılan hizmet hesabı (1. nesil için) hem de Compute Engine varsayılan hizmet hesabı (2. nesil için) üzerindeki tüm gerekli izinlerle eşleşecek şekilde değiştirebilirsiniz.

Eşzamanlılığı kullanma

2. nesil işlevlerin önemli bir avantajı, tek bir işlev örneğinin aynı anda birden fazla isteğe hizmet verebilmesidir. Bu, son kullanıcıların yaşadığı yeni başlatma sayısını önemli ölçüde azaltabilir. Eşzamanlılık varsayılan olarak 80'e ayarlanır ancak 1 ila 1.000 arasında herhangi bir değere ayarlayabilirsiniz:

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // set concurrency value
    concurrency: 500
  },
  (req, res) => {
    // ...
});

Eşzamanlılığı ayarlamak performansı artırabilir ve işlevlerin maliyetini düşürebilir. Eşzamanlı isteklere izin ver bölümünde eşzamanlılık hakkında daha fazla bilgi edinin.

Global değişken kullanımını denetleme

Eşzamanlılık göz önünde bulundurulmadan yazılan 1. nesil işlevler, her istekte ayarlanan ve okunan global değişkenler kullanabilir. Eşzamanlılık etkinleştirildiğinde ve tek bir örnek aynı anda birden fazla isteği işlemeye başladığında, eşzamanlı istekler genel değişkenleri aynı anda ayarlamaya ve okumaya başladığından işlevinizde hatalar oluşabilir.

Yükseltme sırasında işlevinizin CPU'sunu gcf_gen1 olarak ayarlayabilir ve 1. nesil davranışını geri yüklemek için concurrency değerini 1 olarak ayarlayabilirsiniz:

const {onRequest} = require("firebase-functions/v2/https");

exports.date = onRequest({
    // TEMPORARY FIX: remove concurrency
    cpu: "gcf_gen1",
    concurrency: 1
  },
  (req, res) => {
    // ...
});

Ancak bu, 2. nesil işlevlerin performans avantajlarını ortadan kaldırdığı için uzun vadeli bir çözüm olarak önerilmez. Bunun yerine, işlevlerinizdeki global değişkenlerin kullanımını denetleyin ve hazır olduğunuzda bu geçici ayarları kaldırın.

Trafiği yeni 2. nesil işlevlere taşıma

Bir işlevin bölgesini veya tetikleyici türünü değiştirirken olduğu gibi, 2. nesil işleve yeni bir ad vermeniz ve trafiği yavaş yavaş bu işleve geçirmeniz gerekir.

Aynı ada sahip bir işlevi 1. nesilden 2. nesile yükseltmek ve firebase deploy çalıştırmak mümkün değildir. Bu durumda şu hata mesajı gösterilir:

Upgrading from GCFv1 to GCFv2 is not yet supported. Please delete your old function or wait for this feature to be ready.

Taşıma stratejisi, işlevinizin kullandığı tetikleyici türüne bağlıdır.

Çağrılabilir, Görev Sırası ve HTTP tetikleyicilerini taşıma

Bu tetikleyiciler doğrudan çağırmalardır. 2. nesil işlevin yeni bir adı (ve HTTP tetikleyicileri için yeni bir URL) olacağından, istemcileri güncelleyerek trafiği taşıyabilirsiniz.

  1. Kodunuzdaki işlevi yeniden adlandırın (örneğin, myCallable işlevini myCallableV2 olarak yeniden adlandırın).
  2. İşlevi dağıtın. Hem 1. nesil hem de 2. nesil işlevler artık çalışıyor.
  3. İstemci kodunuzu veya arayanınızı, yeni 2. nesil işlevin adını ya da URL'sini işaret edecek şekilde güncelleyin.
  4. Tüm trafik yeni işleve yönlendirildikten sonra Firebase CLI'nın firebase functions:delete komutunu kullanarak 1. nesil işlevi silin.

Arka plan tetikleyicilerini taşıma

Arka plan tetikleyicileri (ör. Pub/Sub, Cloud Firestore ve Cloud Storage tetikleyicileri), projenizdeki etkinliklere yanıt verir. Geçiş sırasında etkinlikleri kaçırmamak için hem 1. nesil hem de 2. nesil işlevleri geçici olarak yan yana çalıştırmanız gerekir.

Geçiş döneminde her iki işlev de aynı etkinlikte tetiklenir. Bu durumda, işletme mantığınız her etkinlik için iki kez çalışır. Devam etmeden önce işlevinizin idempotent olduğundan emin olun.

  1. Mevcut 1. nesil işlevi kodunuzda tutarak ve aynı etkinlik kaynağını dinleyen 2. nesil işlevi ekleyerek 2. nesil işlevi 1. nesil işlevin yanına ekleyin.

    import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing 1st gen function ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("V1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 passthrough function ---
export const myPubSubV2 = onMessagePublished("my-topic", async ({ message, context }) => {
  console.log("v2 handler triggering V1 for event:", context.eventId);
  // Call the v1 function's handler
  await myPubSub.run(message, context);
});

  2. firebase deploy komutunu çalıştırın. Her iki işlev de artık etkin ve aynı etkinlikleri dinliyor.

  3. 2. nesil işlevin trafik aldığını doğrulayın. Her iki işlevin günlüklerini de izleyin. 2. nesil işlevin tüm etkinlikler için çağrıldığından ve çağrıların başarılı olduğundan emin olun.

  4. İşlevin doğru şekilde çalıştığından emin olduğunuzda gerçek iş mantığını 1. nesil işlevden 2. nesil işlevin gövdesine taşıyın. Geçiş yöntemini kullandıysanız myPubSub.run() çağrısını kaldırın.

    import * as functions from "firebase-functions/v1";
import { onMessagePublished } from "firebase-functions/v2/pubsub";

// --- Existing v1 function (to be removed next) ---
export const myPubSub = functions.pubsub.topic("my-topic").onPublish((message, context) => {
  console.log("v1 handler running for event:", context.eventId);
  // ... existing v1 function logic ...
});

// --- New v2 function with full logic ---
export const myPubSubV2 = onMessagePublished("my-topic", ({ message, context }) => {
  console.log("v2 handler running for event:", context.eventId);
  // ... existing v1 function logic WAS MOVED HERE ...
});

    Bu değişikliği dağıtın.

  5. 1. nesil işlev tanımını kodunuzdan kaldırın ve yeniden dağıtın. CLI, 1. nesil işlevi Google Cloud konumundan silmenizi ister.