روال‌های مطلوب پس‌از انتقال

پس‌از انتقال از 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 Tasks.

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

حذف نصب کیت

برای برداشتن کیت و همه نمونه‌های آن، این دستور را اجرا کنید:

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

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

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

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

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

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

درطول نصب یا اولین استقرار، از شما خواسته می‌شود همه پارامترهای کیت را پیکربندی کنید (مگر اینکه پیکربندی را از افزونه‌ای منتقل کرده باشید). این پارامترها در فایل .env در فهرست راهنمای پیکربندی نمونه کیت شما ذخیره می‌شوند. برای مثال، اگر نمونه کیتی با نام firestore-bigquery-export در پروژه 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 را حذف کنید و مستقر کنید، درطول استقرار از شما خواسته می‌شود:

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.my-project
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 قدیمی، ازجمله کیت تابع و کیت توسعه نرم‌افزار 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

    » firebase ext:list
i  extensions: ensuring 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.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. پیکربندی را برای هر نمونه صادر کنید:

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

    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 شما قرار داده شده‌اند، اما اگر به کیت‌های تابع منتقل نشده باشید، به‌صورت روزانه به آن‌ها نیاز ندارید. می‌توانید آن‌ها را از پروژه‌تان به هر مکان ذخیره‌سازی مناسب دیگری منتقل کنید تا در آینده درصورت نیاز از آن‌ها استفاده کنید یا آن‌ها را حذف کنید.