بهترین شیوه‌های پس از مهاجرت

پس از مهاجرت از Firebase Extensions به یک کیت تابع ، نمونه‌های کیت خود را به عنوان Cloud Functions نسل دوم استاندارد در پروژه Firebase خود مدیریت می‌کنید. این راهنما نحوه نصب کیت‌های تابع جدید را مستقیماً از npm بدون مهاجرت یک افزونه موجود، به‌روزرسانی پارامترهای کیت و گزینه‌های سراسری، ارتقاء نسخه‌های بسته npm با انتشار به‌روزرسانی‌ها توسط ناشران و بازگرداندن یک مهاجرت در صورت نیاز را پوشش می‌دهد.

استفاده از یک کیت تابع از یک بسته npm بدون مهاجرت

اگر از یک افزونه مهاجرت نمی‌کنید، استفاده از یک کیت تابع شامل دو بخش است:

نصب کیت

شما می‌توانید با استفاده از دستور CLI زیر، یک کیت تابع نصب کنید:

firebase functions:kits:install --package <npm-package-name>

مثال کار شده:

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i  function-kits/firestore-bigquery-export/source/package.json is unchanged
i  function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i  function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i  functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i  functions: Building TypeScript source...
✔  Wrote configuration info to firebase.json

i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1

✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project

✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing

# Omitting many more parameters for brevity

✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

i  functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i  functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠  functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.

تغییر گزینه‌های پیش‌فرض سراسری

برای پیکربندی گزینه‌های سراسری برای نمونه کیت خود، فایل index.ts واقع در function-kits/<your-kit-id>/source/src/index.ts را تغییر دهید.

اگر می‌خواهید پیش‌فرض‌ها در تمام نمونه‌های کیت به اشتراک گذاشته شوند، آن‌ها را مستقیماً در index.ts تنظیم کنید. در غیر این صورت، پارامترهایی ایجاد کنید که به ازای هر نمونه تنظیم شوند، طبق مثال‌ها و دستورالعمل‌های مستند شده در index.ts .

استقرار کیت

برای استقرار کیت تابع خود، دستور زیر را اجرا کنید:

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

مثال کار شده:

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!

نصب و راه‌اندازی کیت شامل مراحل زیر است:

  • function-kits/firestore-bigquery-export/source را ایجاد می‌کند که شامل منبع کیت، از جمله یک فایل index.ts پایه است که بسته کیت را وارد و صادر می‌کند و در عین حال پارامتری را تنظیم می‌کند که به شما امکان می‌دهد برای هر نمونه از کیت، مکان متفاوتی را انتخاب کنید.
  • function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> را ایجاد کرده و آن را با داده‌های پیکربندی وارد شده برای تابع پر می‌کند. اگر به‌روزرسانی‌های آینده پارامترهای جدیدی اضافه کنند، در استقرار بعدی از شما پرسیده می‌شود.
  • منابع مورد نیاز Google Cloud برای اجرای این کیت، از جمله یک حساب کاربری سرویس با نقش‌های خاص IAM، توابع، محرک‌های Eventarc و صف‌های وظایف Cloud را ایجاد می‌کند.

اگر چندین نمونه از کیت را در یک پروژه دارید، می‌توانید این دستورات را برای ایجاد و استقرار نمونه‌های جدید از همان کیت تکرار کنید. همچنین می‌توانید یک نمونه کیت را در چندین پروژه Firebase با پیکربندی‌های مختلف (مثلاً یک پروژه مرحله‌بندی و یک پروژه تولید) مستقر کنید. برای کسب اطلاعات بیشتر در مورد تنظیمات پیشرفته، به بخش مهاجرت‌های پیشرفته مراجعه کنید.

حذف نصب یک کیت

برای حذف کیت و تمام نمونه‌های آن، دستور زیر را اجرا کنید:

firebase functions:kits:uninstall --kit <kit-id>

این کار تمام نمونه‌ها و پیکربندی‌های آنها را حذف می‌کند و منبع کیت را از دیسک حذف می‌کند.

برای حذف فقط یک نمونه از کیت، دستور زیر را اجرا کنید:

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

اگر فقط یک نمونه از کیت دارید، این کل کیت را حذف نصب می‌کند.

به‌روزرسانی پیکربندی کیت

در طول نصب یا اولین استقرار، از شما خواسته می‌شود که تمام پارامترهای کیت خود را پیکربندی کنید (مگر اینکه پیکربندی را از یک افزونه منتقل کرده باشید). این پارامترها در فایل .env در دایرکتوری پیکربندی نمونه کیت شما ذخیره می‌شوند. برای مثال، اگر یک نمونه کیت با نام firestore-bigquery-export در project my-project دارید، فایل .env در مسیر function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project قرار دارد.

به شکل زیر است:

DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1

اگر مقدار پیکربندی مورد نظر برای تغییر را می‌دانید، می‌توانید آن را مستقیماً در فایل .env ویرایش کنید. اگر ترجیح می‌دهید از اعلان تعاملی که در حین نصب و استقرار اجرا می‌شود استفاده کنید، پارامترهایی را که می‌خواهید تغییر دهید از فایل .env حذف کرده و نمونه کیت را مجدداً مستقر کنید. از شما خواسته می‌شود که این پارامترها را در حین استقرار وارد کنید.

برای مثال، اگر خط COLLECTION_PATH=posts حذف کرده و deploy کنید، در طول deploy از شما خواسته می‌شود که آن را وارد کنید: 

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:

Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)

نگهداری و ارتقاء یک کیت عملکردی

ناشران ممکن است بسته‌های npm خود را به مرور زمان برای رفع اشکالات، اضافه کردن ویژگی‌ها، به‌روزرسانی وابستگی‌ها یا رفع آسیب‌پذیری‌های امنیتی به‌روزرسانی کنند. توصیه می‌کنیم از این نسخه‌ها به‌روز باشید و به‌روزرسانی‌ها را نصب کنید - به‌خصوص آن‌هایی که آسیب‌پذیری‌های امنیتی را برطرف می‌کنند.

دستور functions:kits:install یک کدبیس ایجاد می‌کند که یک کیت را به عنوان یک بسته npm نصب می‌کند و تمام توابع آن را برای هر نمونه از کیت شما صادر می‌کند. برای ارتقاء یک کیت، نسخه بسته را به‌روزرسانی کنید و سپس هر نمونه از کیت خود را مجدداً مستقر کنید تا تغییرات اعمال شود.

تعیین اینکه آیا یک کیت به‌روزرسانی دارد یا خیر

به دایرکتوری source کیت خود در function-kits/<your-kit-id>/source بروید. از این دایرکتوری source ، دستور زیر را اجرا کنید تا گزارشی در مورد تمام بسته‌های npm قدیمی، از جمله کیت تابع و SDK Cloud Functions خود دریافت کنید: 

npm outdated

اگر از قبل از ابزاری برای شناسایی وابستگی‌هایی که نیاز به به‌روزرسانی دارند استفاده می‌کنید، مانند Dependabot برای GitHub، توصیه می‌کنیم دایرکتوری کیت خود را در آن گردش کار ادغام کنید.

به‌روزرسانی یک کیت

برای به‌روزرسانی کیت و وابستگی‌های آن به آخرین نسخهٔ غیر بحرانی (به‌جز به‌روزرسانی‌های اصلی نسخه که ممکن است حاوی تغییرات بحرانی باشند)، دستور زیر را اجرا کنید: 

npm update --save

اگر فقط می‌خواهید بسته‌ی کیت تابع را به‌روزرسانی کنید و هیچ بسته‌ی دیگری را به‌روزرسانی نکنید، نام بسته را به npm update ارسال کنید: 

npm update <package-name> --save

برای ارتقاء یک بسته به آخرین نسخه اصلی (که می‌تواند تغییرات اساسی ایجاد کند)، دستور زیر را اجرا کنید: 

npm update --save <npm-package-name>@latest

مستندات بسته و یادداشت‌های انتشار را بررسی کنید تا ببینید چه چیزی تغییر کرده است و آیا قبل یا بعد از استقرار، برای جلوگیری از تغییرات مخرب، نیاز به انجام اقدامات اضافی دارید یا خیر.

استقرار نمونه‌های به‌روزرسانی‌شده

اجرای npm update فقط کد منبع محلی شما را به‌روزرسانی می‌کند. برای به‌روزرسانی توابع در حال اجرای خود در فضای ابری، آن‌ها را مجدداً مستقر کنید. می‌توانید با اجرای دستور زیر، تمام توابع موجود در پروژه خود، از جمله تمام کیت‌های تابع، را مجدداً مستقر کنید: 

firebase deploy --only functions

لغو یک مهاجرت

برای لغو انتقال، ابتدا افزونه را دوباره نصب کنید. می‌توانید از فایل .env کیت برای یافتن مقادیر پیکربندی مورد نیاز در طول نصب استفاده کنید.

پس از استقرار افزونه، نمونه کیت را حذف نصب کنید (اگر آخرین نمونه باقی‌مانده باشد، کل کیت حذف نصب می‌شود): 

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

ذخیره پیکربندی‌های افزونه برای مهاجرت در آینده

بعد از ۳۱ مارس ۲۰۲۷، شما قادر به دریافت پیکربندی افزونه‌های موجود نخواهید بود. اگر نمی‌توانید قبل از ۳۱ مارس ۲۰۲۷ مهاجرت کنید، اکیداً توصیه می‌کنیم افزونه خود را ذخیره کنید تا در صورت تصمیم به مهاجرت پس از این تاریخ، بتوانید از آن استفاده کنید.

  1. لیستی از شناسه‌های نمونه افزونه خود را دریافت کنید:

    می‌توانید از دستور ext:list CLI برای دریافت لیستی از تمام نمونه‌های افزونه در پروژه Firebase خود استفاده کنید: 

    firebase ext:list --project <project-id>

    مثال کار شده: 

    firebase ext:list --project my-project

    » firebaselocal ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in ajp-testing:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3   │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export      │ ACTIVE │ 0.3.2   │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

    دستور ext:list همچنین دارای فرمت خروجی JSON است و اگر ابزار jq را نصب کرده باشید، می‌توانید از آن برای دریافت لیستی از تمام شناسه‌های نمونه برای یک پروژه استفاده کنید: 

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    مثال کار شده: 

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    خروجی: 

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. پیکربندی را برای هر نمونه صادر کنید:

    برای هر نمونه، می‌توانید با اجرای دستور export زیر، پیکربندی آن را روی دیسک ذخیره کنید: 

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

    مثال کار شده: 

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    خروجی: 

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  functions: Saving exported extensions config as a Function Kits .env file
i  functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control.
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing

    روی دیسک، می‌توانید خروجی این نمونه افزونه را در مکانی مانند <instance-id>/.env.<project-id> پیدا کنید. در این مثال، این فایل در firestore-bigquery-export/.env.my-project قرار دارد.

    شما می‌توانید این فرآیند را برای هر نمونه یک بار تکرار کنید، و این مجموعه‌ای از فایل‌های .env را با تمام پیکربندی‌های نمونه افزونه شما ایجاد می‌کند که می‌توانند بعداً به عنوان بخشی از مهاجرت مورد استفاده مجدد قرار گیرند.

  3. فایل‌های .env اکسپورت شده را به مکان بهتری منتقل کنید:

    فایل‌های .env اکسپورت شده از افزونه‌های شما مستقیماً در پروژه Firebase شما قرار گرفتند، اما اگر به کیت‌های تابع مهاجرت نکرده باشید، به صورت روزانه به آنها نیاز ندارید. می‌توانید آنها را از پروژه خود به هر مکان ذخیره‌سازی مناسب دیگری منتقل کنید تا زمانی که در آینده به آنها نیاز داشته باشید یا آنها را حذف کنید.