Firebase Extensions'ı Cloud Functions'a geçiş için hazırlama

Bu kılavuzda, uzantılarınızı kullanımdan kaldırılan Firebase Extensions ortamından, kullanıcılarınızın kendi Cloud Functions ortamlarında yükleyip dağıttığı bir işlev olarak Firebase (2. nesil) kod tabanına nasıl taşıyacağınız gösterilmektedir.

Bu, önerilen taşıma yoludur. Firebase, resmi npm eşdeğerlerine sahip uzantıların bir listesini tutar. Bu kılavuz, kendi uzantınızı oluşturma sürecinde size yol gösterir.

Bu kılavuzda örnek olarak Stream Firestore to BigQuery (firestore-bigquery-export) uzantısı kullanılmıştır. Her bölüm, @firebase/firestore-bigquery-export paketi olarak, taşıma işleminden önce uzantının nasıl göründüğünü ve işlemden sonra nasıl göründüğünü gösteren bir çalışılmış örnekle sona erer.

Uzantıları taşıma hakkında daha fazla bilgi ve yardım almak için kaydolun.

Firebase Extensions sürümünden nasıl geçiş yapacağınızla ilgili sorularınız varsa firebase-extensions-migrator-support-external@google.com adresinden bize ulaşabilirsiniz. Ayrıca, kılavuzu 2. nesil işlevlerinizi paketleme, test etme ve dağıtma hakkında daha fazla bilgiyle güncellediğimizde bu gruba e-posta göndereceğiz.

Bu gruba katılmak için firebase-extensions-migrator-support-external+subscribe@google.com adresine ileti gönderin. Bu adresten üyelik isteği e-postasıyla yanıt verilir. "Bu Gruba Katıl" düğmesini tıklamadan e-postayı yanıtlamanız gerekir.

Başlamadan önce

Bu taşıma işlemini tamamlamak için Cloud Functions'nın aşağıdaki özelliklerini kullanacaksınız:

• Parametreli Yapılandırma. extension.yaml içinde bildirdiğiniz her parametre, paket kodunuzda tanımlanmış bir parametre haline gelir.

• Bildirim temelli IAM rolleri ve gerekli API'ler. extension.yaml içinde bildirdiğiniz her rol requiresRole(...) çağrısı, her API ise işlev kodunuzda requiresAPI(...) çağrısı olur. Dağıtım sırasında Firebase KSA, bildirilen rolleri yönetilen bir çalışma zamanı hizmeti hesabına atar ve bildirilen API'leri sizin adınıza etkinleştirir.

• Cloud Functions kod tabanları için yaşam döngüsü etkinlikleri. Cloud Functions kod tabanları artık Firebase Extensions'ye benzer yaşam döngüsü etkinliklerini destekliyor. Yükleme zamanı ve güncelleme zamanı kurulumunu yaşam döngüsü kancaları afterFirstDeploy(...) ve afterRedeploy(...) ile tanımlayın. Bunlar, extension.yaml içinde tanımladığınız lifecycleEvents yerine geçer.

Uzantıyı Envantere Ekleme

Uzantınızın envanterini çıkararak başlayın: Uzantının bildirdiği, gönderdiği ve belgelediği her şeyin tam listesi. Böylece her davranışın 2. nesil işlevde tanımlanmış bir hedefi olur ve taşıma sırasında hiçbir şey kaybolmaz.

Aşağıdakilerin her birini inceleyin ve bulgularınızı not edin:

• Parametrelerinizi, işlevlerinizi, etkinliklerinizi, IAM rollerinizi, gerekli API'lerinizi, gizli dizilerinizi ve yaşam döngüsü kancalarınızı bildiren extension.yaml.

• functions/ (işlev kodunuzu, bağımlılıklarınızı, derleme yapılandırmanızı, tetikleyicilerinizi ve görev sırası işlevlerinizi içerir).

• Kurulum adımlarını, uyarıları ve faturalandırma notlarını içeren README.md, PREINSTALL.md ve POSTINSTALL.md.

• scripts/ (içe aktarma, doldurma, IAM, onarım veya taşıma yardımcı programları ve uzantıyla birlikte gönderdiğiniz diğer tüm araçlar).

Ardından, extension.yaml içindeki her öğenin npm paketinde nereye gideceğine karar verin:

• Kullanıcı yapılandırmasını Cloud Functions parametrelerine dönüştürün (5. bölüm).

• Gizli anahtarları Cloud Functions gizli anahtarlara dönüştürün (Bölüm 6).

• IAM rollerini requiresRole(...) bildirimlerine dönüştürme (bölüm 8).

• Gerekli Google API'lerini uygun yerlerde requiresAPI(...) bildirimlerine dönüştürün (8. bölüm).

• Yükleme ve güncelleme kancalarını afterFirstDeploy(...) ve afterRedeploy(...) beyanlarına dönüştürün (bölüm 8).

Çözümlü örnek: Firestore'u BigQuery'a aktarma

firestore-bigquery-export/extension.yaml ve functions/ dosyalarının okunması şu envanteri oluşturur:

Uzantı, gizli parametreler gibi herhangi bir tür belirtmediğinden bu kılavuzun 6. bölümünde taşınacak bir şey yoktur. Etkinlik tetikleyici zaten 2. nesil. Yalnızca görev sırası işlevleri hâlâ 1. nesil (3. bölümde ele alınmıştır).

package.json dosyasını güncelleme

Uzantınızın package.json dosyasını güncelleyin. Tek bir uzantıyı taşıyorsanız bu, kök package.json olabilir. Tek bir depoda çok sayıda uzantı taşıyorsanız her uzantıya kendi paketini verin.

Minimum SDK sürümleri. firebase-functions >= 7.3 ve firebase-admin >= 14.2.0'ı bağımlılık olarak bildirin. firebase-functions sürümünüzü de eş bağımlılık olarak bildirin.

{
  "name": "<package-name>",
  "version": "1.0.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": ">=22"
  },
  "peerDependencies": {
    "firebase-functions": "^7.3.0"
  },
  "dependencies": {
    "firebase-functions": "^7.3.0",
    "firebase-admin": "^14.2.0"
  }
}

Kullanıcılarınızın Cloud Functions projesinde, kitaplığınızın yazıldığı SDK'nın aynı sürümü bulunması için firebase-functions'ı normal bağımlılığınıza ek olarak eş bağımlılık olarak bildirin.

Çözümlü örnek: Firestore'u BigQuery'a aktarma

Önce. Uzantının functions/package.json dosyası özeldir, uzantı kimliğini adlandırır ve firebase-functions'ı doğrudan bağımlılık olarak bildirir:

{
  "name": "firestore-bigquery-export",
  "main": "lib/index.js",
  "private": true,
  "dependencies": {
    "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
    "firebase-admin": "^14.2.0",
    "firebase-functions": "^6.3.2"
  }
}

Sonra. Yayınlanabilir bir paket: kapsamlı ad, dışa aktarma eşlemesi ve firebase-functions, peerDependencies'ye taşındı:

{
  "name": "@firebase/firestore-bigquery-export",
  "version": "0.1.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".":     { "types": "./lib/index.d.ts", "default": "./lib/index.js" },  },
  "engines": { "node": ">=22" },
  "peerDependencies": { "firebase-functions": "^7.3.0" },
  "dependencies": {
      "@firebaseextensions/firestore-bigquery-change-tracker": "^2.0.4",
      "firebase-admin": "^14.2.0",
      "firebase-functions": "^7.3.0"
    }
}

1. nesil işlevleri 2. nesil işlevlere yükseltme

Uzantınız hâlâ 1. nesil işlevleri dışa aktarıyorsa her işlevi 2. nesil eşdeğerine dönüştürün. firebase-functions/... modüllerinden içe aktarın ve işlev seçeneklerinde çalışma zamanı ayarlarını iletin.

2. nesil yamalı etkinlik yapı çözme ile yeniden yazma çabalarını en aza indirebilirsiniz. 2. nesil SDK artık V1 parametrelerini etkinlik nesnesindeki alanlar olarak gösterdiğinden işlev mantığınızı yeniden yazmanız gerekmez. Bu sayede, yapı çözülmüş/adlandırılmış parametreleri kullanabilir ve işletme mantığınızı değiştirmeden tutabilirsiniz.

Önce. 1. nesil:

import * as functions from "firebase-functions/v1";

export const sync = functions.firestore
  .document("{collectionId}/{documentId}")
  .onWrite(async (change, context) => {
    await handleWrite(change.before, change.after, context.params);
  });

Sonra. 2. nesil:

import { onDocumentWritten } from "firebase-functions/firestore";

export const syncV2 = onDocumentWritten(
  { document: "{collectionId}/{documentId}" },
  async ({change,context}) =>
    await handleWrite(change.before, change.after, context.params);
);

1. nesil ve 2. nesil işlevler arasındaki farkların kapsamlı listesi için Cloud Functions sürüm karşılaştırmasına bakın.

Uzantı parametrelerini ve gizli anahtarlarını dönüştürme

Parametreleri dönüştürme

extension.yaml içinde belirttiğiniz her parametre Cloud Functions parametresine dönüşür.

Doğrudan ortam okumalarını dönüştürme:

const collectionPath = process.env.COLLECTION_PATH;

Cloud Functions parametrelerine:

import { defineString } from "firebase-functions/params";
import { onDocumentWritten} from "firebase-functions/firestore";

const collectionPath = defineString("COLLECTION_PATH");

// Pass the param directly when used as a placeholder (e.g. trigger path)
export const sync = onDocumentWritten(
  { document: collectionPath },
  async (event) => {
    // Call .value() to read the string inside a handler
    const path = collectionPath.value();
    await handleWrite(path, event);
  }
);

Bir işleyici içindeki dizeyi okumak için collectionPath.value() kullanın. Yer tutucunun beklendiği yerlerde (ör. işlev tetikleyici yolu) doğrudan collectionPath kullanın.

Firebase CLI, parametrelerinizi keşfeder ve değerlerini .env, .env.projectId dosyasından okur veya dağıtım sırasında kullanıcılarınızdan ister. Mevcut bir kurulumdaki değerlerin aktarılması için aynı parametre adlarını kullanın.

Kodunuzda belirtilen parametre adlarını hiçbir şekilde değiştirmemeniz önemlidir. Uzantı taşıma işlemi, mevcut son kullanıcı parametre değerini otomatik olarak korur ancak yalnızca adlar değişmediğinde.

Çalışan örnek: Firestore'u BigQuery'a aktarın Önce. extension.yaml içinde tanımlanan ve config.ts içinde ham ortam değişkeni olarak okunan bir parametre:

# extension.yaml
-   param: COLLECTION_PATH
  label: Collection path
  type: string
  required: true

// functions/src/config.ts
collectionPath: process.env.COLLECTION_PATH,

Sonra. Bir defineString; KSA bunu keşfeder ve .env'den okur:

// src/config.ts
import { defineString } from "firebase-functions/params";

collectionPath: defineString("COLLECTION_PATH", {
  label: "Collection path",
  // We now support "nonEmpty: true" to ensure a value other than the empty string
  // is entered, analagous to "required: true" in extensions.yaml
  input: { text: { nonEmpty: true} }
}),

Parametre adı değişmediğinden mevcut bir .env dosyası çalışmaya devam eder.

Gizli anahtarları dönüştürme

extension.yaml dosyasında, türü: secret olan gizli anahtarları bildirirsiniz. Uzantıların çalışma zamanı bunları saklayıp bağlar. Böylece uzantı kodunuz process.env.PARAM_NAME'i doğrudan okuyabilir. Tipik bir Cloud Functions kod tabanında her bir Gizli Anahtarı açıkça tanımlar ve bağlarsınız:

import { defineSecret } from "firebase-functions/params";
import { onRequest } from "firebase-functions/https";

const apiKey = defineSecret("API_KEY");
export const fn = onRequest({ secrets: [apiKey] }, handler);

Uzantınız bir npm paketine/kitine taşındıktan sonra gizli referanslar, son kullanıcının .env dosyasında yönetilir. Kodunuzda belirtilen gizli adları hiçbir şekilde değiştirmemeniz önemlidir. Taşıma sırasında son kullanıcı sırları buna göre taşınır.

Çalışma örneği: Cloud Firestore adresinden e-posta tetikleme

Önce. MAIL_COLLECTION ve SMTP_PASSWORD, config.ts dosyasında ham ortam değişkenleri olarak okunur:

# extension.yaml
-   param: MAIL_COLLECTION
  label: Email documents collection
  type: string
  default: mail
  required: true

-   param: SMTP_PASSWORD
  label: SMTP password
  type: secret

// functions/src/config.ts
mailCollection: process.env.MAIL_COLLECTION,
smtpPassword: process.env.SMTP_PASSWORD,

Sonra. Bir defineString ve bir defineSecret; KSA her ikisini de keşfeder ve .env'dan okur

import { defineString, defineSecret } from "firebase-functions/params";
import { onDocumentWritten } from "firebase-functions/firestore";

const mailCollection = defineString("MAIL_COLLECTION",{ label: "Email documents collection",
 default: "mail"
});

const smtpPassword = defineSecret("SMTP_PASSWORD", { label: "SMTP password" });

export const processQueue = onDocumentWritten(
  { document: `${mailCollection}/{documentId}`, secrets: [smtpPassword] },
  async (event) => {
    const collection = mailCollection.value();
    const password = smtpPassword.value();
    // ...
  }
);

Dahili görev sırası çağrılarını taşıma

Bazı uzantılar, Firebase Admin SDK kullanarak işi kendi işlev kodlarının içinden kendi görev kuyruklarına ekler. Bu, gönderilen bir görevi almaktan farklıdır (Yükseltme işlevleri ve Dönüştürme yaşam döngüsü kancaları bölümlerinde ele alınmıştır). Burada kodunuz, queue.enqueue(...) işlevini çağıran üreticidir.

Admin SDK'nın önceki sürümlerinde, aynı uzantıdaki bir görev sırası işlevini hedeflemek için uzantıların kendi uzantı örneği kimliklerini ikinci bir parametre olarak iletmesi gerekiyordu. `firebase-admin` 14.2.0 sürümünden itibaren bu işlem ne gereklidir ne de önerilir. Görev Sırası API'si artık varsayılan olarak aynı bağlamdaki (ör. uzantı) görev sıralarını hedefleyecektir. Bu parametreyi kodunuzdan hem uzantı hem de bağımsız işlevler olarak kaldırmak güvenlidir ve önerilir. Bu parametrenin kaldırılması, taşınabilirlik ve ileriye dönük uyumluluk sağlar.

Sıraya alma çağrısıyla ilgili diğer her şey (locations/region/functions/name kaynak yolu, görev yükü ve yeniden deneme mantığınız) aynı kalır.

Cloud Tasks ile işlevleri sıraya alma hakkında daha fazla bilgi için /docs/functions/task-functions adresini ziyaret edin.

Önce. 1. nesil uzatma kablosu

import { getFunctions } from "firebase-admin/functions";

const queue = getFunctions().taskQueue(
  `locations/${config.location}/functions/syncBigQuery`,
  process.env.EXT_INSTANCE_ID, // extension instance ID, injected by the runtime
);
await queue.enqueue(taskData);

Sonra. 2. nesil uzantı

import { getFunctions } from "firebase-admin/functions";
import { region } from "firebase-functions/params";

const queue = getFunctions().taskQueue(
  `locations/${region.value()}/functions/syncBigQuery`);
await queue.enqueue(taskData);

Kuyruğa alma çağrınız, önekli bir kod tabanını hedefliyorsa keşfedilen işlev adı da önekli olur (örneğin, orders-syncBigQuery).

Gerekli API'leri ve IAM rollerini beyan etme

Uzantınızın IAM ve API gereksinimlerini extension.yaml dosyasından çıkarıp koda taşıyın:

import { requiresAPI, requiresRole } from "firebase-functions"

requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");

Bildirim temelli güvenlik ile Firebase CLI, kod tabanı için yönetilen bir çalışma zamanı hizmet hesabı oluşturur veya günceller ve bu hesaba, bildirilen tüm rollerin birleşimini verir. Son API daha dar bir modeli desteklemediği sürece, kod tabanındaki tüm işlevlerin bu rollerle çalıştığını kullanıcılarınıza bildirin.

Çözümlü örnek: Firestore'u BigQuery'a aktarma

Önce. extension.yaml dosyasında belirtilir. Uzantılar çalışma zamanı, API'yi etkinleştirmiş ve rolleri yönetilen bir hesaba vermiştir:

apis:
  -   apiName: bigquery.googleapis.com
roles:
  -   role: bigquery.dataEditor
  -   role: datastore.user
  -   role: bigquery.user

Sonra. requiresAPI ve requiresRole ile kodda belirtilir:

import { requiresAPI, requiresRole } from "firebase-functions/";
requiresAPI("bigquery.googleapis.com",
  "Needed to write changelog rows and views");
requiresRole("roles/biguqery.dataEditor");
requiresRole("roles/datastore.user");
requiresRole("roles/bigquery.user");

Yaşam döngüsü kancalarını dönüştürme

Uzantınız örneğin getExtensions().runtime(), setProcessingState veya setFatalError çağırıyorsa bu çağrıları silin. Bu çağrılar, normal şekilde dağıtılan 2. nesil bir işlevden çağrıldığında hata verir. Yaşam döngüsü durumu artık bu durum izlemenin kullanılmadığı afterFirstDeploy ve afterRedeploy tarafından belirleniyor.

Firebase Extensions, kullanıcı bir uzantı yüklediğinde, güncellediğinde veya yeniden yapılandırdığında kurulumu çalıştırabilir. npm paketinizde, koda eşdeğer yaşam döngüsü işlemleri bildirin.

Tek seferlik kurulum için:

import { afterFirstDeploy } from "firebase-functions/lifecycle";
import { onTaskDispatched } from "firebase-functions/tasks";

export const runInitialSetup = onTaskDispatched(async (request) => {
  await initializeResources(request.data);
});

afterFirstDeploy({
  task: {
    function: "runInitialSetup",
    body: {}
  }
});

Yapılandırma veya kod güncellemeleri için:

import { afterRedeploy } from "firebase-functions/lifecycle";

afterRedeploy({
  task: {
    function: "runInitialSetup",
    body: { reconcile: true }
  }
});

Yaşam döngüsü işlemlerinizi idempotent yapın. Gönderme veya yürütme başarısız olursa kullanıcılarınızın bunları manuel olarak yeniden çalıştırması gerekebilir:

firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME

Çözümlü örnek: Firestore'u BigQuery'a aktarma

Önce. Uzantılar çalışma zamanı tarafından desteklenen lifecycleEvents, extension.yaml içinde:

lifecycleEvents:
  onInstall:
    function: initBigQuerySync
    processingMessage: Configuring BigQuery Sync.
  onUpdate:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync
  onConfigure:
    function: setupBigQuerySync
    processingMessage: Configuring BigQuery Sync

Sonra. Kodda belirtilir. Görev, ilk dağıtımda BigQuery sağlar:

import { afterFirstDeploy, afterRedeploy } from "firebase-functions/lifecycle";

afterFirstDeploy({ task: { function: "initBigQuerySync" } });
afterRedeploy({ task: { function: "setupBigQuerySync" } });

Sağlama işlemi, aynı sonucu veren bir işlemdir. Bu nedenle, yeniden çalıştırma işlemi veri kümesini, tabloyu ve görünümleri uzlaştırır. Kullanıcılar, firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME komutunu kullanarak manuel olarak yeniden çalıştırabilir.

Kullanıcılarınız için doküman kurulumu

• Aşağıdakileri en azından açıklayan bir paket README yazın:

• Paketin gerektirdiği .env değerleri.

• Paketin gerektirdiği gizli anahtarlar ve mevcut gizli anahtar değerlerini nasıl taşıyacağınız.

• Paketin requiresRole(...) ile bildirdiği IAM rolleri.

• Paketin etkinleştirdiği veya gerektirdiği Google API'leri.

• Paketin bildirdiği yaşam döngüsü kancaları ve bunların nasıl manuel olarak yeniden çalıştırılacağı.

• Faturalandırma notları.

• Orijinal uzantıya kıyasla ne değişti?

Çözümlü örnek: Firestore'u BigQuery'a aktarma

Paket README'sinde somut bir "neler değişti?" tablosu yer alır:

2. nesil işlevinizi test etme

Artık, dağıtıldığında uzantınızın yeni yüklenmesiyle aynı şekilde davranacak 2. nesil bir işleviniz olmalıdır. Son adım, doğrulama yapmak ve bu süreçte yanlışlıkla ortaya çıkan sorunları düzeltmektir.

firebase-tools >= 15.24.0 sürümünü kullandığınızdan emin olun ve dönüştürülmüş 2. nesil işlevinizi davranışını test etmek için uygun kaynaklara sahip bir test projesine dağıtın. Uzantınızı test ederek daha önce bir test projesi oluşturduysanız şu komutu kullanın:

firebase deploy --only functions

Bu komutu girdikten sonra, parametre değerlerini isteyen sihirbazı, uzantı için Firebase konsolundaki yükleme formunu doldurmuş gibi doldurun.

Çözümlü örnek: Firestore'u BigQuery'a aktarma

Cloud Firestore ile BigQuery arasındaki senkronizasyonun uçtan uca olduğunu doğrularız:

1. Cloud Firestore konsolunda, henüz yoksa COLLECTION_PATH (kullanıcılar) olarak ayarladığınız koleksiyonu oluşturun.
2. Herhangi bir değerle herhangi bir alanı içeren bigquery-mirror-test adlı bir doküman oluşturun.
3. BigQuery konsolunda, ham değişiklik günlüğü tablosunu sorgulayın. Aşağıdaki bilgileri içeren tek bir satır içermelidir:

SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

1. En son görünümü sorgulayın. Bu sorgu, mevcut tek doküman olan bigquery-mirror-test için en son değişiklik etkinliğini döndürmelidir.

SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

1. bigquery-mirror-test içindeki Cloud Firestore dokümanını silin. En son görünümden kaybolur ve ham değişiklik günlüğü tablosuna DELETE etkinliği eklenir.

Tek bir dokümanın tüm geçmişini şu yöntemlerle inceleyebilirsiniz:

SELECT *
   FROM `PROJECT_ID.analytics.users_raw_changelog`
   WHERE document_name = "bigquery-mirror-test"
   ORDER BY timestamp ASC

Uzantıyı test etme işleminden farklılıklar:

• Tetikleyici, fsexportbigquery (isteğe bağlı olarak kod tabanı önekli) olarak dağıtılır, ext-<instanceId>-fsexportbigquery olarak değil. Bu adı Cloud Functions kontrol panelinde ve günlüklerde arayın.
• Kodunuz artık Firebase Local Emulator Suite'da normal şekilde çalışacak. Emülatörde kullanılacak parametrelerin değerini .env.local ile ayarlayabilirsiniz. Ayrıca, Unit testing of Cloud Functions bölümünde açıklandığı gibi firebase-functions-test SDK'sını kullanarak kodunuzda birim testi yapabilirsiniz.
• Artık uzantılar çalışma zamanı tarafından sağlama yapılmıyor. Dağıtımdan sonra değişiklik günlüğü tablosu eksikse kurulum görevini manuel olarak yeniden çalıştırın: firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME. Görev, idempotent olduğundan yeniden çalıştırıldığında veri kümesi, tablo ve görünümler uzlaştırılır.
• Parametre değerleri yükleme formundan değil .env'dan gelir. Bu nedenle, .env tamamlandıktan sonra firebase deploy'un yeniden çalıştırılması etkileşimli olmaz.