بعد نقل البيانات من Firebase Extensions إلى حزمة دوال، يمكنك إدارة نُسخ الحزمة كدوال Cloud Functions عادية من الجيل الثاني في مشروع Firebase. يتناول هذا الدليل كيفية تثبيت حِزم الدوال الجديدة مباشرةً من npm بدون نقل بيانات إضافة حالية، وتحديث مَعلمات الحِزم والخيارات العامة، وترقية إصدارات حِزم npm عندما يُصدر الناشرون تحديثات، والتراجع عن عملية نقل البيانات إذا لزم الأمر.
استخدام حزمة دوال من حزمة npm بدون نقل البيانات
إذا لم تكن تنقل البيانات من إضافة، يتألف استخدام حزمة الدوال من جزأين:
تثبيت المجموعة
يمكنك تثبيت حزمة دوال باستخدام أمر واجهة سطر الأوامر التالي:
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 المطلوبة لتشغيل هذه الحزمة، بما في ذلك حساب خدمة يتضمّن أدوارًا ووظائف محدّدة في "إدارة الهوية وإمكانية الوصول"، ومشغّلات Eventarc، وقوائم انتظار "مهام Cloud".
إذا كان لديك نُسخ متعددة من الحزمة في المشروع نفسه، يمكنك تكرار هذه الأوامر لإنشاء نُسخ جديدة من الحزمة نفسها ونشرها. يمكنك أيضًا نشر مثيل حزمة واحد في عدة مشاريع على 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 القديمة، بما في ذلك حزمة الدوال وحزمة تطوير البرامج (SDK) لـ Cloud Functions:
npm outdated
إذا كنت تستخدم أداة لتحديد التبعيات التي تحتاج إلى تحديث، مثل Dependabot لـ GitHub، ننصحك بدمج دليل حزمة الأدوات في سير العمل هذا.
تعديل حزمة
لتحديث الحزمة والتبعيات إلى أحدث إصدار لا يؤدي إلى عطل (باستثناء تحديثات أرقام الإصدارات الرئيسية التي قد تحتوي على تغييرات قد تؤدي إلى عطل)، نفِّذ الأمر التالي:
npm update --save
إذا أردت تحديث حزمة function kit فقط وليس أي حزم أخرى، يمكنك تمرير
اسم الحزمة إلى 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>
حفظ إعدادات الإضافات لعملية نقل بيانات مستقبلية
بعد 31 مارس 2027، لن تتمكّن من جلب إعدادات الإضافة الحالية. إذا لم تتمكّن من نقل البيانات قبل 31 مارس 2027، ننصحك بشدة بحفظ الإضافة في حال قرّرت نقل البيانات بعد هذا التاريخ.
احصل على قائمة بأرقام تعريف مثيلات الإضافات:
يمكنك استخدام الأمر
ext:listفي واجهة سطر الأوامر للحصول على قائمة بجميع نُسخ الإضافات في مشروع 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صدِّر الإعدادات لكل مثيل:
بالنسبة إلى كل مثيل، يمكنك حفظ إعداداته على القرص من خلال تنفيذ أمر التصدير التالي:
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تتضمّن جميع إعدادات مثيل الإضافة التي يمكن إعادة استخدامها لاحقًا كجزء من عملية نقل البيانات.انقل ملفات
.envالتي تم تصديرها إلى مكان أفضل:تم وضع ملفات
.envالتي تم تصديرها من إضافاتك مباشرةً في مشروع Firebase، ولكنّها ليست ضرورية للاستخدام اليومي إذا لم يتم نقلها إلى حِزم الدوال. يمكنك نقلها من مشروعك إلى أي موقع تخزين مناسب آخر حتى تحتاج إليها في المستقبل أو تختار حذفها.