Bu kılavuzda, uzantılarınızı kullanımdan kaldırılan Firebase Extensions ortamından, Cloud FunctionsFirebase (2. nesil) kod tabanınızda yükleyip dağıtabileceğiniz bir işlev kitine nasıl taşıyacağınız gösterilmektedir.
Firebase Extensions Uzantı oluşturma, güncelleme ve kaldırma işlemlerinin tüm yönlerini yönetir. İşlev kitleri, uzantıların özelliklerini normal 2. nesil Cloud Functions for Firebase olarak paketler. İşlev kitleri standart olduğundan Cloud Functions, bunları Firebase projenizdeki Firebase CLI'yı kullanarak oluşturur, günceller, siler ve sorunlarını giderirsiniz. Bu kılavuz, işlevlerinizi yönetmeye ve güncellemeler yayınlandıkça bunları kullanmaya başlamanıza yardımcı olur.
Bu kılavuzda, Stream Cloud Firestore to BigQuery
uzantısı (firestore-bigquery-export), taşıma işleminin her adımındaki komutları ve komut çıkışını gösteren bir örnek olarak kullanılır.
Taşıma yolunuzu belirleme
Firebase, tüm Firebase Extensions yayıncılarını, uzantılarının yerine npm'de yayınlanan işlev kitleri oluşturmaya teşvik eder. Uzantılarınız için işlev kiti değişimi olup olmadığını birkaç farklı şekilde kontrol edebilirsiniz:
- Projeniz için Firebase konsolunun Uzantılar sayfasına gidin. Yüklü her uzantı, işlev kiti yerine kullanılabilecek bir uzantı olup olmadığını gösterir.
Yüklü uzantılarınızdan hangilerinin resmi alternatifleri olduğunu görmek için bir terminalde
firebase ext:listprojenizde Firebase komutunu çalıştırın:firebase ext:list --project my-projecti extensions: ensuring required API firebaseextensions.googleapis.com is enabled... ✔ extensions: required API firebaseextensions.googleapis.com is enabled i extensions: list of extensions installed in my-project: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2 │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/storage-resize-images │ firebase │ storage-resize-images │ ACTIVE │ 0.3.6 │ 2026-06-03 17:41:24 │ │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting
Uzantınız için resmi bir işlev kiti değişimi varsa npm'de işlev kitlerine taşıma bölümünü kullanarak taşıyabilirsiniz.
Yayınlanmış bir alternatif bulamıyorsanız tüm uzantılar açık kaynaklı olduğundan uzantı kodunu çatallayıp kendi alternatifinizi oluşturabilirsiniz. Bunu yapmak için Kendi oluşturduğunuz işlev kitine taşıma rehberini uygulayın.
| Taşıma yolunu seçin: | npm'deki işlev kitlerine geçiş yapma Kendiniz oluşturduğunuz bir işlev kitine geçiş yapma |
npm'deki işlev kitlerine geçiş
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 sürümünü >= 15.32.0 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.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreatorroles/cloudfunctions.admin(Herkese açık uç noktalar içinsetIamPermissionsyapmanı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.
Bir KSA iş akışı seçin
Bir uzantı örneğinden npm'de bulunan bir işlev kitine geçmek için aşağıdaki seçeneklerden birini belirleyin:
- (Önerilir)
ext:migrateCLI komutunu kullanarak taşıma yapın. Bu komut, değiştirdiği uzantının yüklemesini kaldırmadan önce işlev kiti değiştirmenizi dağıtır. - Function Kits KSA komutlarını kullanarak taşıma Uzantınızı güncellemek, işlev kiti yüklemek, uzantı gibi yapılandırmak, kiti dağıtmak ve uzantıyı kaldırmak için ayrı komutlar kullanabilirsiniz. Bu sayede, komutları yeniden sıralama veya adımlar arasında ek işlemler yapma konusunda daha fazla esneklik elde edersiniz.
ext:migrate kullanarak taşıma
Her uzantı örneği için bir kez olmak üzere, aşağıdaki komutu çalıştırarak taşıma işlemini başlatın:
firebase ext:migrate --project <project-id>
Bu komut, aşağıdaki adımlarda size yol gösterir:
- Resmi işlev kiti yerine geçeni olan bir uzantıyı taşımayı seçme.
- Bu uzantının belirli bir örneğini seçme
- Gerekirse uzantıyı en son sürüme güncelleyin.
- İşlev kitini yükleme, bir örneği uzantı örneğinin yapılandırıldığı şekilde yapılandırma.
- İşlev kitini dağıtma.
- İşlev kitinin başarıyla dağıtıldığını ve varsa tüm yaşam döngüsü kancalarının çalıştırıldığını doğrulama.
- Uzantı örneğinin yüklemesi kaldırılıyor.
Taşımak istediğiniz uzantıyı veya uzantı örneğini biliyorsanız aşağıdaki komut satırı işaretlerini kullanarak belirtin:
firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>
# or
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>
Özellikle Google tarafından listelenen resmi bir yedek paket değilse geçiş yapmak istediğiniz paketi biliyorsanız --package işaretini kullanarak belirtin:
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>
İşlev kiti dağıtımını doğrulama
Kitteki firebase deploy'nın 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.
İşlev kiti README dosyasını inceleyin.
Bazı kitler, işlev kitleri tarafından otomatik olarak işlenenlerin dışında ek çalışmalar gerektirebilir. Yüklediğiniz kitin README bölümünü inceleyin ve ek talimatları uygulayın.
Function Kits CLI'yı kullanarak taşıma
Başlamadan önce, kite taşımak istediğiniz uzantının örnek kimliğini ve yerine kullanılacak kitin npm paket adını belirleyip not alın. Bu ikisini de firebase ext:list çıkışını kullanarak bulabilirsiniz. ext:list kullanımına ilişkin bir örnek için Taşıma yolunuzu belirleme bölümüne bakın.
1. 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 aşağıdaki komutları kullanarak:
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.
2. Değiştirme işlevi kiti örneğini inceleyin ve yükleyin
İşlev kitini aşağıdaki CLI komutunu kullanarak yükleyebilirsiniz:
firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>
Yükleme sırasında kitiniz için bir örnek kimliği seçtiğinizde, taşıma talimatlarında daha sonra kullanmak üzere bu kimliği not edin.
Kit yüklendikten sonra, Firebase projenizde yeni bir dizin oluşturulur. Bu dizin, uzantınızın yerini alan kiti içeren npm paketini function-kits/<kit-name>/source ve Firebase'nın dağıtması ve özel yapılandırma ayarlaması için bu işlevleri dışa aktaran temel bir index.ts dosyasını içerir.
Kitle ilgili README dosyasını inceleyin ve burada listelenen ek talimatları uygulayın.
Aynı projede kiti birden fazla kez kullanıyorsanız aynı kitin yeni örneklerini oluşturmak için bu komutu tekrarlayabilirsiniz. Ayrıca, farklı yapılandırmalara sahip iki farklı Firebase projesine (örneğin, bir hazırlık projesi ve bir üretim projesi) tek bir kit örneği dağıtabilirsiniz. Bu gelişmiş kurulumlar hakkında daha fazla bilgi edinmek için Gelişmiş taşıma işlemleri başlıklı makaleyi inceleyin.
Çözülmüş örnek:
firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project
3. İş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>
4. 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.
5. 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-testingexport-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.