این راهنما به شما نشان می‌دهد که چگونه افزونه‌های خود را از محیط منسوخ‌شده Firebase Extensions به یک کیت تابع منتقل کنید که می‌توانید آن را در Cloud Functions خود برای پایگاه کد Firebase (نسل دوم) نصب و مستقر کنید.
Firebase Extensions همه جنبه‌های ایجاد، به‌روزرسانی، و برداشتن افزونه‌ها را مدیریت می‌کرد. کیت‌های تابع قابلیت‌های افزونه‌ها را به‌عنوان Cloud Functions for Firebase نسل دوم معمولی بسته‌بندی می‌کنند. چون کیت‌های تابع استاندارد Cloud Functions هستند، آن‌ها را بااستفاده از Firebase CLI در پروژه Firebase خود ایجاد، به‌روزرسانی، حذف، و عیب‌یابی می‌کنید. این راهنما شما را آماده می‌کند تا توابع خود را مدیریت کنید و به‌روزرسانی‌ها را به‌محض دردسترس قرار گرفتن اعمال کنید.
در سراسر این راهنما، از افزونه Stream Cloud Firestore to BigQuery (firestore-bigquery-export) به‌عنوان نمونه‌ای استفاده می‌شود که فرمان‌ها و خروجی فرمان را برای هر مرحله از انتقال نشان می‌دهد.
مسیر انتقال را تعیین کنید
Firebase همه ناشران Firebase Extensions را تشویق می‌کند تا جایگزین‌هایی برای افزونه‌هایشان به‌عنوان کیت‌های تابع منتشرشده در npm ایجاد کنند. به چند روش مختلف می‌توانید بررسی کنید که آیا جایگزینی برای کیت تابع برای افزونه‌هایتان دردسترس است یا نه:
- به صفحه «افزونه‌ها» در کنسول Firebase برای پروژه‌تان بروید. هر افزونه‌ای که نصب کرده‌اید نشان می‌دهد که آیا جایگزین کیت تابع دردسترس دارد یا نه.
firebase ext:listرا در پروژه Firebase خود در پایانه اجرا کنید تا ببینید کدام‌یک از افزونه‌های نصب‌شده شما جایگزین رسمی دارند: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
اگر کیت تابع جایگزین رسمی برای افزونه‌تان دردسترس است، می‌توانید آن را بااستفاده از بخش انتقال به کیت‌های تابع در npm منتقل کنید.
اگر نمی‌توانید جایگزین منتشرشده‌ای پیدا کنید، می‌توانید کد افزونه را منشعب کنید و جایگزین خودتان را ایجاد کنید زیرا همه افزونه‌ها متن‌باز هستند. برای انجام این کار، راهنمای انتقال به کیت تابع خودساخته را دنبال کنید.
| انتخاب مسیر انتقال: | انتقال به کیت‌های تابع در npm انتقال به کیت تابع خودساخته |
انتقال به کیت‌های تابع در npm
بررسی محدودیت‌های شناخته‌شده انتقال
قبل‌از شروع انتقال نمونه افزونه، بررسی کنید که آیا راه‌اندازی شما از هریک از ویژگی‌های زیر استفاده می‌کند که نیاز به راه‌حل جایگزین دارند یا هنوز در کیت‌های تابع پشتیبانی نمی‌شوند:
- مخازن Docker سفارشی و کلیدهای KMS به راه‌حل دستی نیاز دارند Cloud Functions for Firebase از پارامترهای سیستم جایگزین برای پیکربندی مخزن Docker سفارشی یا «کلید رمزگذاری مدیریت‌شده توسط مشتری» (کلید KMS) پشتیبانی نمی‌کند. اگر افزونه شما هرکدام از این پارامترها را پیکربندی می‌کند، به راه‌حل پرسشگان مراجعه کنید.
قبل از شروع
باید Firebase CLI را راه‌اندازی کنید و
Firebase
پروژه را مقداردهی اولیه کنید. هنگام استفاده از CLI، مطمئن شوید
از نسخه >= 15.32.0 firebase-tools استفاده می‌کنید که دارای دستورات جدید انتقال
و کیت تابع است.
اجازه‌ها و نقش‌های حساب موردنیاز
بسته به آنچه باید توسط Firebase CLI درطول انتقال ایجاد و پیکربندی شود، حسابی که برای اصالت‌سنجی با Firebase و Google Cloud استفاده می‌کنید باید نقش‌های زیر را داشته باشد:
roles/firebaseextensions.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreatorroles/cloudfunctions.admin(اگر لازم استsetIamPermissionsرا برای نقاط پایانی عمومی انجام دهید)roles/secretmanager.admin(درصورت استفاده از اسرار)roles/serviceusage.serviceUsageAdmin(اگر لازم است میاناهای برنامه‌سازی کاربردی جدیدی را فعال کنید)
توصیه می‌کنیم از حسابی استفاده کنید که قبلاً افزونه نصب کرده و تابع مستقر کرده است، زیرا اکثر این اجازه‌ها قبلاً اعطا شده‌اند. اگر حساب انتقالی شما به نقش‌های بیشتری نیاز دارد، Google Cloudدستورالعمل‌های IAM را برای افزودن آن‌ها دنبال کنید.
انتخاب گردش کار CLI
برای انتقال از نمونه افزونه به کیت تابع دردسترس در npm، یکی از گزینه‌های زیر را انتخاب کنید:
- (توصیه‌شده) بااستفاده از فرمان CLI
ext:migrateانتقال دهید. این فرمان کیت تابع جایگزین را قبل‌از حذف نصب افزونه‌ای که جایگزین آن می‌شود مستقر می‌کند. - بااستفاده از فرمان‌های CLI کیت‌های تابع انتقال دهید. می‌توانید از فرمان‌های جداگانه برای به‌روزرسانی افزونه، نصب کیت تابع، پیکربندی آن مانند افزونه، استقرار کیت، و حذف نصب افزونه استفاده کنید. این کار انعطاف‌پذیری بیشتری برای تغییر ترتیب فرمان‌ها یا انجام کارهای اضافی بین مراحل فراهم می‌کند.
انتقال بااستفاده از ext:migrate
یک‌بار برای هر نمونه افزونه، با اجرای دستور زیر انتقال را شروع کنید:
firebase ext:migrate --project <project-id>
این فرمان شما را در این زمینه‌ها راهنمایی می‌کند:
- انتخاب افزونه‌ای برای انتقال که جایگزین کیت تابع رسمی برای آن دردسترس است.
- انتخاب نمونه خاصی از آن افزونه.
- درصورت لزوم، افزونه را به جدیدترین نسخه به‌روز کنید.
- درحال نصب کیت تابع، پیکربندی نمونه به‌صورت یکسان با نحوه پیکربندی نمونه افزونه.
- درحال استقرار کیت تابع.
- تأیید اینکه کیت تابع باموفقیت مستقر شده است و همه قلاب‌های چرخه حیات، درصورت وجود، اجرا شده‌اند.
- درحال حذف نصب نمونه افزونه.
اگر افزونه یا نمونه افزونه خاصی را که می‌خواهید انتقال دهید می‌شناسید، آن را بااستفاده از پرچم‌های خط فرمان زیر مشخص کنید:
firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>
# or
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>
اگر بسته خاصی را که می‌خواهید به آن منتقل شوید می‌شناسید، به‌ویژه اگر بسته جایگزین رسمی فهرست‌شده توسط Google نباشد، آن را بااستفاده از پرچم --package مشخص کنید:
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>
درستی‌سنجی استقرار کیت تابع
برای تأیید اینکه firebase deploy کیت هیچ خطایی نداشته است،
گزارش‌های استقرار را بررسی کنید تا ببینید آیا قلاب‌های چرخه حیات فعال شده‌اند یا نه. افزونه‌های پرطرفدار، مثل Stream Cloud Firestore به BigQuery، از قلاب‌های چرخه حیات استفاده می‌کنند. در زیر نمونه‌ای از ظاهر قلاب چرخه حیات هنگام راه‌اندازی آورده شده است:
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
این پیام‌های گزارش موارد زیر را تأیید می‌کنند:
- یک قلاب چرخه حیات پیدا و اجرا شد.
- تکلیفی در صف تکلیف مرتبط با قلاب چرخه حیات قرار گرفت.
- پیوندی به Cloud Logging ارائه شده است تا بتوانید تأیید کنید که تکلیف بدون خطا تکمیل شده است.
پیوند گزارش‌ها را به کنسول Google Cloud دنبال کنید تا مطمئن شوید که هیچ خطایی در گزارش‌ها وجود ندارد و رویداد صف وظیفه شما با موفقیت پردازش شده است. اگر رویداد چرخه حیات با موفقیت اجرا نشد، می‌توانید با اجرای دستور زیر آن را دوباره راه‌اندازی کنید:
firebase functions:lifecycle:run <hook-name> <codebase>
اگر برای اولین‌بار است که نمونه کیت تابع را مستقر می‌کنید، این دستور را اجرا کنید:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
اگر درطول اعتبارسنجی تصمیم گرفتید این انتقال را متوقف یا واگرد کنید، می‌توانید بااستفاده از دستورالعمل‌های موجود در حذف نصب افزونه، کیت را حذف نصب کنید.
پس‌از اینکه تأیید کردید استقرار اولیه کیت تابع شما با موفقیت تکمیل شده است، باید تأیید کنید که عملکرد کیت درواقع طبق انتظار کار می‌کند. چون خود افزونه هنوز درحال اجرا است، باید دقت کنید که آنچه بررسی می‌کنید فقط این نباشد که یکی از این دو کار کرده است، زیرا افزونه کار می‌کرده است و همچنان کار خواهد کرد.
در مواردی که پردازش تغییر نمی‌کند و نتایج تکراری از افزونه و کیت نمی‌بینید، بهترین گزینه این است که پس‌از راه‌اندازی عملکرد کیت، گزارش‌های کیت را مستقیماً بررسی کنید.
نمونه کارشده: جاری‌سازی Cloud Firestore به BigQuery
با «افزونه جاری‌سازی Cloud Firestore به BigQuery»، اگر رویداد یکسانی به کیت و افزونه ارسال شود، نوشتن در هر دو «جدول گزارش تغییرات خام» (*_raw_changelog) و جدول آخرین نما (*_raw_latest) تکرارزدایی خواهد شد. بنابراین نمی‌توانید از وجود هرگونه ردیف یا ردیف تکراری در BigQuery برای اعتبارسنجی عملکرد کیت استفاده کنید.
می‌توانید گزارش‌های توابع را کمی پس‌از نوشتن در مجموعه Firestore خود
بااستفاده از firebase functions:logs مشاهده کنید و به‌دنبال ورودی گزارشی بگردید که نشان می‌دهد
نوشتن را با موفقیت پردازش کرده است. برای این کیت با شناسه نمونه پیش‌فرض
firestore-bigquery-export به‌صورت زیر خواهد بود:
2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2
اگر گزارش‌های زیادی دارید، می‌توانید بااستفاده از فرمان زیر، فیلتر را به عملکرد کیت خاصی محدود کنید:
firebase functions:log --only <function name>
برای پیدا کردن نام‌های تابع خاص برای نمونه کیت، می‌توانید از فرمان زیر استفاده کنید:
firebase functions:list | grep kit-<kit instance id>
برای این مثال:
firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery │ v2 │ google.cloud.firestore.document.v1.written │
│ kit-firestore-bigquery-export-initBigQuerySync │ v2 │ taskQueue │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2 │ taskQueue │
│ kit-firestore-bigquery-export-syncBigQuery │ v2 │ taskQueue │
مرور کردن README کیت تابع
برخی‌از کیت‌ها ممکن است به کارهای بیشتری فراتر از آنچه به‌طور خودکار توسط کیت‌های تابع انجام می‌شود نیاز داشته باشند. README را برای کیتی که نصب می‌کنید مرور کنید و هرگونه
دستورالعمل اضافی را دنبال کنید.
انتقال بااستفاده از کیت‌های تابع CLI
قبل‌از شروع، شناسه نمونه افزونه‌ای را که می‌خواهید به کیت منتقل کنید و نام بسته npm کیت جایگزین آن را شناسایی و یادداشت کنید. می‌توانید
هر دو را بااستفاده از خروجی firebase ext:list پیدا کنید. برای دیدن نمونه‌ای از استفاده از
ext:list،
تعیین مسیر انتقال را ببینید.
۱. نمونه افزونه‌تان را به جدیدترین نسخه ارتقا دهید
باید افزونه‌تان را به جدیدترین نسخه به‌روز کنید تا تفاوت بین نمونه افزونه و کیت جایگزین آن به حداقل برسد. اگر افزونه‌تان ارتقا داده نشود، ممکن است تغییرات قابل‌توجه و مخربی بین نمونه افزونه شما و کیت جایگزین آن ایجاد شود. پیکربندی صادرشده ممکن است به‌دلیل تغییرات پارامتر در نسخه‌های مختلف با آنچه کیت انتظار دارد مطابقت نداشته باشد.
بسته به اینکه افزونه‌تان کجا نصب شده است، از یکی از گزینه‌های زیر برای به‌روزرسانی آن استفاده کنید:
- از کنسول Firebase
- از Firebase CLI بااستفاده از:
firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>
اگر این مرحله را رد کنید، CLI از شما می‌خواهد که هنگام صادر کردن پیکربندی، اگر افزونه شما در جدیدترین نسخه نیست، آن را ارتقا دهید.
۲. نمونه کیت تابع جایگزین را مرور و نصب کنید
می‌توانید کیت تابع را بااستفاده از فرمان CLI زیر نصب کنید:
firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>
وقتی شناسه نمونه‌ای را برای کیت خود درطول نصب انتخاب می‌کنید، حتماً آن را یادداشت کنید تا بعداً در دستورالعمل‌های انتقال از آن استفاده کنید.
پس‌از نصب کیت، فهرست راهنمای جدیدی در پروژه Firebase شما با مکانی مانند function-kits/<kit-name>/source ایجاد می‌شود که حاوی بسته npm با کیت جایگزین افزونه شما و یک فایل پایه index.ts است که آن توابع را برای Firebase صادر می‌کند تا پیکربندی سفارشی را مستقر و تنظیم کند.
README را برای کیت مرور کنید و هرگونه دستورالعمل اضافی فهرست‌شده در آنجا را دنبال کنید.
اگر چند نمونه از کیت در یک پروژه دارید، می‌توانید این فرمان را تکرار کنید تا نمونه‌های جدیدی از همان کیت ایجاد کنید. همچنین می‌توانید یک نمونه کیت را در دو پروژه Firebase مختلف با پیکربندی‌های متفاوت (مثلاً یک پروژه آماده‌سازی و یک پروژه تولید) مستقر کنید. برای کسب اطلاعات بیشتر درباره این راه‌اندازی‌های پیشرفته، به انتقال‌های پیشرفته مراجعه کنید.
نمونه حل‌شده:
firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project
۳. نمونه کیت تابع را به‌طور یکسان با افزونه پیکربندی کنید
باید این نمونه کیت را با پیکربندی یکسان با افزونه‌ای که جایگزین آن می‌شود سفارشی‌سازی کنید. می‌توانید پیکربندی نمونه افزونه‌تان را به فایل .env صادر کنید که داده‌های پیکربندی مرجع محرمانه، متغیر محیطی، و پارامتر را برای همه Cloud Functions، ازجمله کیت‌ها، ذخیره می‌کند. برای
صادر کردن مستقیم آن به فایل پیکربندی کیت، این دستور را اجرا کنید:
firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>
در پایان این مرحله، اطلاعات پیکربندی این نمونه در فایل .env مختص پروژه در فهرست راهنمای پیکربندی نمونه شما ذخیره می‌شود، مانند:
function-kits/<kit-name>/config-<instance-id>/.env.<project-id>
۴. کیت جایگزین را مستقر و درستی‌سنجی کنید
اکنون که کیت نصب شده و به‌عنوان مجموعه‌ای از توابع دردسترس است، می‌توانید جایگزین کیت را مستقر کنید. کیت‌های تابع مانند توابع استاندارد کار می‌کنند، که در آن هر نمونه کیت به‌عنوان یک پایگاه کد جداگانه برای سازمان‌دهی توابع شما عمل می‌کند. می‌توانید انتخاب کنید که همه توابع یا فقط یک نمونه کیت خاص را مستقر کنید. هنگام انتقال یک نمونه افزونه، فقط آن نمونه کیت را مستقر کنید.
اگر کیت شما از پارامترهای جدیدی استفاده می‌کند که در نمونه افزونه‌ای که از آن مهاجرت کرده‌اید وجود نداشت، Firebase CLI در ابتدای فرایند استقرار از شما می‌خواهد آن‌ها را وارد کنید. این مورد در این مثال کاربردی از افزونه به‌روز firestore-bigquery-export انتظار نمی‌رود، اما بسیاری از کیت‌ها برای هر منبع راه‌انداز رویداد که توسط کیت استفاده می‌شود، پارامتر جدیدی درخواست می‌کنند. به‌عنوان بخشی از این انتقال، کیت‌های به‌روزشده از توابع نسل دوم استفاده می‌کنند، درحالی‌که افزونه‌ها قبلاً از توابع نسل اول استفاده می‌کردند. در نسل دوم، توابع نزدیک به منابع رویدادشان قرار دارند و به‌عنوان پارامتر اضافی اضافه می‌شوند. در به‌روزرسانی‌های آینده، اگر پارامترهای جدیدی اضافه شود، CLI در استقرار بعدی از شما درخواست می‌کند.
نمونه حل‌شده:
firebase deploy --only functions:firestore-bigquery-export --project my-project
برونداد:
=== 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!
برای تأیید اینکه firebase deploy کیت هیچ خطایی نداشته است،
گزارش‌های استقرار را بررسی کنید تا ببینید آیا قلاب‌های چرخه حیات فعال شده‌اند یا نه. افزونه‌های پرطرفدار، مثل Stream Cloud Firestore به BigQuery، از قلاب‌های چرخه حیات استفاده می‌کنند. در زیر نمونه‌ای از ظاهر قلاب چرخه حیات هنگام راه‌اندازی آورده شده است:
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
این پیام‌های گزارش موارد زیر را تأیید می‌کنند:
- یک قلاب چرخه حیات پیدا و اجرا شد.
- تکلیفی در صف تکلیف مرتبط با قلاب چرخه حیات قرار گرفت.
- پیوندی به Cloud Logging ارائه شده است تا بتوانید تأیید کنید که تکلیف بدون خطا تکمیل شده است.
پیوند گزارش‌ها را به کنسول Google Cloud دنبال کنید تا مطمئن شوید که هیچ خطایی در گزارش‌ها وجود ندارد و رویداد صف وظیفه شما با موفقیت پردازش شده است. اگر رویداد چرخه حیات با موفقیت اجرا نشد، می‌توانید با اجرای دستور زیر آن را دوباره راه‌اندازی کنید:
firebase functions:lifecycle:run <hook-name> <codebase>
اگر برای اولین‌بار است که نمونه کیت تابع را مستقر می‌کنید، این دستور را اجرا کنید:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
اگر درطول اعتبارسنجی تصمیم گرفتید این انتقال را متوقف یا واگرد کنید، می‌توانید بااستفاده از دستورالعمل‌های موجود در حذف نصب افزونه، کیت را حذف نصب کنید.
پس‌از اینکه تأیید کردید استقرار اولیه کیت تابع شما با موفقیت تکمیل شده است، باید تأیید کنید که عملکرد کیت درواقع طبق انتظار کار می‌کند. چون خود افزونه هنوز درحال اجرا است، باید دقت کنید که آنچه بررسی می‌کنید فقط این نباشد که یکی از این دو کار کرده است، زیرا افزونه کار می‌کرده است و همچنان کار خواهد کرد.
در مواردی که پردازش تغییر نمی‌کند و نتایج تکراری از افزونه و کیت نمی‌بینید، بهترین گزینه این است که پس‌از راه‌اندازی عملکرد کیت، گزارش‌های کیت را مستقیماً بررسی کنید.
نمونه کارشده: جاری‌سازی Cloud Firestore به BigQuery
با «افزونه جاری‌سازی Cloud Firestore به BigQuery»، اگر رویداد یکسانی به کیت و افزونه ارسال شود، نوشتن در هر دو «جدول گزارش تغییرات خام» (*_raw_changelog) و جدول آخرین نما (*_raw_latest) تکرارزدایی خواهد شد. بنابراین نمی‌توانید از وجود هرگونه ردیف یا ردیف تکراری در BigQuery برای اعتبارسنجی عملکرد کیت استفاده کنید.
می‌توانید گزارش‌های توابع را کمی پس‌از نوشتن در مجموعه Firestore خود
بااستفاده از firebase functions:logs مشاهده کنید و به‌دنبال ورودی گزارشی بگردید که نشان می‌دهد
نوشتن را با موفقیت پردازش کرده است. برای این کیت با شناسه نمونه پیش‌فرض
firestore-bigquery-export به‌صورت زیر خواهد بود:
2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2
اگر گزارش‌های زیادی دارید، می‌توانید بااستفاده از فرمان زیر، فیلتر را به عملکرد کیت خاصی محدود کنید:
firebase functions:log --only <function name>
برای پیدا کردن نام‌های تابع خاص برای نمونه کیت، می‌توانید از فرمان زیر استفاده کنید:
firebase functions:list | grep kit-<kit instance id>
برای این مثال:
firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery │ v2 │ google.cloud.firestore.document.v1.written │
│ kit-firestore-bigquery-export-initBigQuerySync │ v2 │ taskQueue │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2 │ taskQueue │
│ kit-firestore-bigquery-export-syncBigQuery │ v2 │ taskQueue │
۵. حذف نصب افزونه
وقتی کیت تابع مستقرشده را درستی‌سنجی کردید، می‌توانید افزونه را حذف نصب کنید تا رفتار آن یک‌بار برای کیت و یک‌بار برای افزونه تکرار نشود. می‌توانید همه افزونه‌ها را از Firebase CLI حذف نصب کنید
صرف‌نظر از اینکه چگونه آن‌ها را نصب کرده‌اید، اگر پرچم --immediate را ارسال کنید:
firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate
نمونه حل‌شده:
firebase ext:uninstall firestore-bigquery-export --project my-project --immediate
برونداد:
i extensions: uninstalling firestore-bigquery-export...
i extensions: deleting extension instance resources in project my-project...
✔ extensions: successfully uninstalled firestore-bigquery-export
انتقال‌های پیشرفته
می‌توانید در چندین پروژه Firebase افزونه داشته باشید که می‌خواهید
با یک پایگاه کد واحد مدیریت کنید. برای مثال، اگر زیرساخت یکسانی را در محیط testing و محیط production مستقر کنید، که هرکدام نمونه documents Cloud Firestore دارند که به BigQuery صادر می‌کنید، ممکن است دو نمونه از افزونه firestore-bigquery-export نصب‌شده داشته باشید:
export-documents-testingexport-documents-production
اگر این دو نمونه افزونه را به دو نمونه کیت تابع در یک پایگاه کد واحد هنگام کار با Firebase CLI منتقل کرده و بااستفاده از firebase deploy --project testing و firebase deploy --project production مستقر کرده باشید، هر استقرار دو نمونه در هر دو محیط testing و production ایجاد می‌کند.
به‌جای آن، دو نمونه افزونه را با یک نمونه کیت تابع
firestore-bigquery-export که در چند پروژه مستقر شده است جایگزین کنید، به‌طوری‌که هر پروژه
پیکربندی خودش را داشته باشد. فهرست پیکربندی شما برای نمونه باید
به‌صورت زیر باشد:
config-export-documents/.env.testing.env.production
هر استقرار در testing و production یک نمونه از کیت شما را
با پیکربندی مربوطه ایجاد می‌کند. فرمان‌های CLI موجود این راه‌اندازی را ایجاد می‌کنند، به‌شرطی که پرچم --project را در هر فراخوانی ext:migrate یا functions:kits:install ارسال کنید.
نمونه حل‌شده:
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
اکنون یک نمونه کیت دارید که برای استقرار در پروژه‌های testing و
production با پیکربندی‌های مربوطه‌شان پیکربندی شده است. اگر نمونه‌ای در پروژه testing ایجاد کنید و فرمان functions:kits:install را برای همان بسته در پروژه production اجرا کنید، گزینه‌ای برای استفاده مجدد از نمونه پیکربندی‌شده برای testing یا نصب نمونه دوم به شما نشان داده می‌شود.