Firebase Extensions'ı kendi oluşturduğunuz bir işlev kitine taşıma

Taşıma yolunu seçin: npm'deki işlev kitlerine geçiş yapma Kendi oluşturduğunuz işlev kitine geçiş yapma

Bir yayıncı, npm'de dağıtılan resmi bir yedek kit oluşturmadıysa bu kılavuz, uzantısını çatallayıp yerel bir işlev kiti olarak ayarlama adımlarında size yol gösterir.

Bilinen taşıma sınırlamalarını kontrol etme

Bir uzantı örneğini taşımaya başlamadan önce, kurulumunuzda aşağıdaki özelliklerden herhangi birinin kullanılıp kullanılmadığını kontrol edin. Bu özellikler için geçici çözüm gerekir veya işlev kitlerinde henüz desteklenmez:

  • Özel Docker depoları ve KMS anahtarları için manuel bir geçici çözüm gerekir Cloud Functions for Firebase, özel bir Docker deposu veya müşteri tarafından yönetilen şifreleme anahtarı (KMS anahtarı) yapılandırmak için sistem parametrelerinin değiştirilmesini desteklemez. Uzantınız bu parametrelerden birini yapılandırıyorsa Soru-Cevap bölümündeki geçici çözüme bakın.

Başlamadan önce

Firebase KSA'yı ayarlamanız ve bir Firebase proje ilk kullanıma hazırlamanız gerekir. KSA'yı kullanırken yeni taşıma ve Functions kiti komutlarını içeren firebase-tools >= 15.32.0 sürümünü kullandığınızdan emin olun.

Gerekli hesap izinleri ve rolleri

Taşıma sırasında Firebase CLI tarafından oluşturulması ve yapılandırılması gerekenlere bağlı olarak, Firebase ve Google Cloud ile kimlik doğrulamak için kullandığınız hesapta aşağıdaki roller olmalıdır:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (Herkese açık uç noktalar için setIamPermissions yapmanız gerekiyorsa)
  • roles/secretmanager.admin (sırlar kullanılıyorsa)
  • roles/serviceusage.serviceUsageAdmin (yeni API'leri etkinleştirmeniz gerekiyorsa)

Bu izinlerin çoğu daha önce verilmiş olacağından, daha önce uzantıların yüklendiği ve işlevlerin dağıtıldığı bir hesabı kullanmanızı öneririz. Taşıdığınız hesabın daha fazla role ihtiyacı varsa bunları eklemek için Google Cloud IAM talimatlarını uygulayın.

Uzantı örneğinizi en yeni sürüme yükseltme

Uzantı örneğiniz ile yedek kiti arasındaki farkı en aza indirmek için uzantınızı en son sürüme güncellemeniz gerekir. Uzantınız yükseltilmezse uzantı örneğiniz ile kit değişimi arasında önemli ve uyumluluğu bozan değişiklikler olabilir. Dışa aktarılan yapılandırma, sürümler arasındaki parametre değişiklikleri nedeniyle kitin beklediğiyle eşleşmeyebilir.

Uzantınızı güncellemek için, yüklendiği yere bağlı olarak aşağıdaki seçeneklerden birini kullanın:

  • Firebase konsolundan
  • Firebase KSA'sından:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Bu adımı atlarsanız uzantınız en son sürümde değilse CLI, yapılandırmayı dışa aktarırken yükseltme yapmanızı ister.

Uzantıyı yerel bir işlev kitine çatallama

Bir uzantıyı yerel işlev kitine dönüştürmeye başlamadan önce uzantı kaynak kodunun Firebase projenizde olduğundan emin olun. Bunu yapmak için, GitHub'dan uzantı deposunu kopyalayın, Firebase proje kökünüzde bir dizin oluşturun ve uzantının functions/ klasörünü ve extension.yaml dosyasını bu dizine kopyalayın:

mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.

Uzantı kaynak kodunuzu 2. nesil bir işleve taşımak için Yayıncı geçiş rehberindeki 1-8. adımları uygulayın. Ardından aşağıdaki adımlarla devam edin.

Yerel kitinizin, dışa aktarılan işlev bölgesini ve gelişmiş parametreleri desteklemesini sağlama

Yerel bir işlev kitinde Firebase CLI, paketi ayarlamak ve taşınan sistem parametrelerini kullanacak şekilde yapılandırmak için index.ts dosyası oluşturmaz. Uzantınız için yapılandırılmış işlev bölgesi ve gelişmiş parametreleri kullanmak üzere index.ts dosyanızı, firebase ext:export --mode functions tarafından dışa aktarılan biçimi bir ortam değişkeni dosyasına okuyacak şekilde ayarlayın.

Özellikle, işlevlerinizi dışa aktaran üst düzey index.ts dosyasında FUNCTION_DEFAULT_REGION için bir parametre tanımlayın ve setGlobalOptions işlevini, KSA tarafından kullanılan index-kit-migration.ts şablonuna benzer şekilde EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION> biçimindeki ortam değişkenleriyle çağırın:

import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";

export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
  input: { text: { nonEmpty: true } },
  description: "Global default region where functions should be deployed. Can be overridden per-function.",
});

setGlobalOptions({
  region: regionParam,
  memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
  timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
    ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
    : undefined,
  vpcConnectorEgressSettings:
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
      ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
      : undefined,
  vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
  maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
    : undefined,
  minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
    : undefined,
  ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
  // Parses a comma-separated string of key:value pairs into a key-value object
  // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
  labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
    ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
        (acc, curr) => {
          const [key, value] = curr.split(":");
          const trimmedKey = key?.trim();
          const trimmedValue = value?.trim();
          if (!trimmedKey || !trimmedValue) {
            return acc;
          }
          acc = acc ?? {};
          acc[trimmedKey] = trimmedValue;
          return acc;
        },
        undefined,
      )
    : undefined,
});

// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";

Taşıma işleminden önce kitinizi test etme

Artık, dağıtıldığında uzantınızın yeni yüklenmesiyle aynı şekilde çalışan yerel bir işlev kitiniz var. Bir sonraki adım, üretim uzantısı örneklerinizi bu sürüme taşımadan önce yanlışlıkla eklenen sorunları doğrulayıp düzeltmektir.

Öncelikle çatalınızı yerel bir kit olarak ekleyin, yapılandırın ve bir test projesine dağıtın. Yerel işlev kitleri Firebase projenizin içinde olmalıdır. Bu nedenle, klonlanmış uzantı deposu Firebase projenizin dışındaysa proje dizininin içine taşıyın. Ardından, yerel bir kit olarak yüklemek için aşağıdaki kit yükleme komutunu çalıştırın:

firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>

Bu komut, ilk test örneğiniz için bir kit kimliği, bir örnek kimliği ve bir yapılandırma seçme konusunda size yol gösterir. Ardından, çatallanmış dizininize işaret eden yerel bir kiti kaydetmek için firebase.json dosyanızı değiştirir. Her örnek için yapılandırmalar function-kits/<kit-id>/config-<instance-id> konumundaki .env dosyasında saklanır.

Yerel kitinizi, davranışını test etmek için uygun kaynaklara sahip bir test projesine dağıtın. Uzantınızı test ederken zaten bir test projesi oluşturduysanız aşağıdaki komutu çalıştırın:

firebase deploy --only functions:<kit-instance-id> --project <test-project-id>

Çözümlü örnek: Cloud Firestore akışını BigQuery'e aktarma (firestore-bigquery-export)

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

  1. Firebase konsolunun Cloud Firestore sayfasında, henüz yoksa COLLECTION_PATH (users) olarak ayarladığınız koleksiyonu oluşturun.
  2. Herhangi bir değer içeren alanları içeren bigquery-mirror-test adlı bir doküman oluşturun.

  3. BigQuery sayfasında, Google Cloud konsolunda ham değişiklik günlüğü tablosunu sorgulayın. Belge oluşturma işlemini kaydeden tek bir satır içermelidir:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Yalnızca mevcut dokümanın (bigquery-mirror-test) en son değişiklik etkinliğini döndürmesi gereken en son görünümü sorgulayın:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Cloud Firestore içindeki bigquery-mirror-test 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, ext-<instanceId>-fsexportbigquery olarak değil, kit-<kit-instance-id>-fsexportbigquery olarak dağıtılır. Bu adı Cloud Functions kontrol panelinde ve günlüklerde bulun.
  • Kodunuz, standart işlevler olarak Firebase Local Emulator Suite içinde çalışır. Emülatörde kullanılacak parametre değerlerini .env.local ile ayarlayabilirsiniz. Ayrıca, firebase-functions-test SDK'sını kullanarak kodunuzu birim testine tabi tutabilirsiniz. Bu işlem, Cloud Functions birim testi başlıklı makalede açıklanmıştır.
  • 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 <kit-instance-id>. 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 kaynağından alınır. Bu nedenle, .env tamamlandıktan sonra firebase deploy yeniden çalıştırıldığında etkileşimli olmaz.

(İsteğe bağlı) Testten sonra temizleme

Testten sonra bu test örneğini kaldırmak istiyorsanız yüklemesini kaldırın:

firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>

Bu işlem, kiti dağıtarak oluşturulan tüm bulut kaynaklarını siler ve örnek yapılandırmasını kaldırır. Kitten yalnızca bir örneğiniz varsa bu işlem, kit girişini firebase.json'dan da kaldırır. Yerel kaynak kodu dizininiz silinmez. Üretim geçişiniz için kiti yüklediğinizde tekrar bir kit kimliği seçebilirsiniz.

Uzantılardan yerel kitinize geçiş yapma

Yerel kitiniz test edildiğine göre, canlı olarak dağıtılan uzantı örneğinizi taşıyabilirsiniz.

1. Değiştirme işlevi kiti örneğini yükleyin.

--no-configure değerini ileterek yerel işlev kitinizi yükleyin. Böylece manuel yapılandırma atlanır ve sonraki adımda mevcut uzantı yapılandırmanız doğrudan bu kit örneğine aktarılabilir:

firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>

2. İşlev kiti örneğini uzantıyla aynı şekilde yapılandırın.

Bu kit örneğini, yerine geçtiği uzantıyla aynı yapılandırmayla özelleştirmeniz gerekir. Uzantı örneği yapılandırmanızı, kitler dahil tüm Cloud Functions için parametre, ortam değişkeni ve gizli referans yapılandırma verilerini depolayan bir .env dosyasına aktarabilirsiniz. Doğrudan kitinizin yapılandırma dosyasına aktarmak için şunu çalıştırın:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

Bu adımın sonunda, bu örneğin yapılandırma bilgileri, örnek yapılandırma dizininizde projeye özel bir .env dosyasına kaydedilir. Örneğin: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

3. Kiti dağıtma ve değiştirme işlemini doğrulama

Kit yüklendiğine ve bir dizi işlev olarak kullanılabildiğine göre artık kit değişimini dağıtabilirsiniz. İşlev kitleri, standart işlevler gibi çalışır. Her kit örneği, işlevlerinizi düzenlemek için ayrı bir kod tabanı görevi görür. Tüm işlevlerinizi veya yalnızca belirli bir kit örneğini dağıtmayı seçebilirsiniz. Tek bir uzantı örneğini taşırken yalnızca bu kit örneğini dağıtın.

Kitiniz, taşıma işlemini yaptığınız uzantı örneğinde bulunmayan yeni parametreler kullanıyorsa Firebase CLI, dağıtım sürecinin başında bu parametreleri ister. Bu, güncel bir firestore-bigquery-export uzantısından alınan bu çalışılmış örnekte beklenmez ancak birçok kit, kit tarafından kullanılan herhangi bir etkinlik tetikleme kaynağı için yeni bir parametre ister. Bu taşıma işlemi kapsamında, güncellenen kitlerde 2. nesil işlevler kullanılır. Uzantılar daha önce 1. nesil işlevleri kullanıyordu. 2. nesilde işlevler, etkinlik kaynaklarının yakınında bulunur ve ek parametre olarak eklenir. Gelecekteki güncellemelerde yeni parametreler eklenirse CLI, bir sonraki dağıtımda sizi uyarır.

Çözülmüş örnek:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Çıkış:

=== Deploying to 'my-project'...
i  deploying functions
i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i  functions: ensuring required API bigquery.googleapis.com is enabled...
i  functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔  functions: required APIs are enabled
i  functions: granting declarative IAM roles to managed service account:
   - BigQuery Data Editor
   - BigQuery User
   - Cloud Datastore User
   - Eventarc Event Receiver
   - roles/run.invoker
✔  functions: successfully granted IAM roles
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i  functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔  functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔  functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔  Deploy complete!

Kitteki firebase deploy öğesinin hatasız olduğunu doğrulamak için dağıtım günlüklerini kontrol ederek yaşam döngüsü kancalarının tetiklenip tetiklenmediğini görün. Stream Cloud Firestore to BigQuery gibi popüler uzantılar yaşam döngüsü kancalarını kullanır. Aşağıda, tetiklendiğinde yaşam döngüsü kancasının nasıl göründüğüne dair bir örnek verilmiştir:

i  functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔  functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i  functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project

Bu günlük mesajları aşağıdakileri doğrular:

  • Bir yaşam döngüsü kancası bulundu ve yürütüldü.
  • Yaşam döngüsü kancasının ilişkili görev kuyruğunda bir görev sıraya alındı.
  • Görevin hatasız tamamlandığını doğrulayabilmeniz için Cloud Logging'e bir bağlantı sağlanır.

Günlüklerde hata olmadığını ve görev sırası etkinliğinizin başarıyla işlendiğini doğrulamak için günlükler bağlantısını kullanarak Google Cloud konsoluna gidin. Yaşam döngüsü olayı başarıyla yürütülmediyse aşağıdaki komutu çalıştırarak yeniden tetikleyebilirsiniz:

firebase functions:lifecycle:run <hook-name> <codebase>

Bir işlev kiti örneğini ilk kez dağıtıyorsanız şu komutu çalıştırın:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Doğrulama sırasında bu taşıma işlemini durdurmak veya geri almak isterseniz Uzantıyı kaldırma bölümündeki talimatları uygulayarak kiti kaldırabilirsiniz.

4. Uzantıyı kaldırma

Dağıtılan işlev kitinizi doğruladıktan sonra, davranışını bir kez kit için, bir kez de uzantı için tekrarlamamak amacıyla uzantınızı kaldırabilirsiniz. --immediate işaretini iletirseniz Firebase CLI'dan tüm uzantıları nasıl yüklediğinizden bağımsız olarak kaldırabilirsiniz:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Çözülmüş örnek:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Çıkış:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Gelişmiş taşıma işlemleri

Tek bir kod tabanıyla yönetmek istediğiniz birden fazla Firebase projenizde uzantılar olabilir. Örneğin, aynı altyapıyı testing ve production ortamlarına dağıtırsanız ve her birinde BigQuery'e aktardığınız bir documents Cloud Firestore örneği varsa firestore-bigquery-export uzantısının iki örneği yüklü olabilir:

  • export-documents-testing
  • export-documents-production

Firebase CLI ile çalışırken bu iki uzantı örneğini tek bir kod tabanında iki işlev kiti örneğine taşıdıysanız ve firebase deploy --project testing ile firebase deploy --project production kullanarak dağıttıysanız her dağıtım hem testing hem de production ortamlarında iki örnek oluşturur.

Bunun yerine, iki uzantı örneğini, her projenin kendi yapılandırmasına sahip olduğu, birden fazla projeye dağıtılan firestore-bigquery-export işlev kiti örneğiyle değiştirin. Örnek için yapılandırma dizininiz şu şekilde görünmelidir:

  • config-export-documents/
    • .env.testing
    • .env.production

testing ve production'ye yapılan her dağıtım, kitinizin ilgili yapılandırmaya sahip bir örneğini oluşturur. Mevcut KSA komutları, --project veya functions:kits:install her çağrıldığında ext:migrate işaretini iletmeniz koşuluyla bu kurulumu oluşturur.

Çözülmüş örnek:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔  Wrote function-kits/firestore-bigquery-export/source/package.json
✔  Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔  Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔  Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i  functions: Running npm install
✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
  --kit-instance export-documents --project testing

# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
  --kit-instance export-documents --project production

Artık testing ve production projelerinize kendi yapılandırmalarıyla dağıtım yapmak üzere yapılandırılmış tek bir kit örneğiniz var. testing projesinde bir örnek oluşturup production projesinde aynı paket için functions:kits:install komutunu çalıştırırsanız testing için yapılandırılan örneği yeniden kullanma veya ikinci bir örnek yükleme seçeneği sunulur.