أفضل الممارسات بعد نقل البيانات

بعد نقل البيانات من 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 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.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 القديمة، بما في ذلك حزمة الدوال وCloud Functions SDK:

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>

حفظ إعدادات الإضافة لعملية نقل بيانات مستقبلية

بعد 31 مارس 2027، لن تتمكّن من استرداد إعدادات إضافة حالية. إذا تعذّر عليك نقل بيانات إضافتك قبل 31 مارس 2027، ننصحك بشدة بحفظها في حال قررت نقلها بعد هذا التاريخ.

  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. صدِّر الإعداد لكل مثيل:

    يمكنك حفظ إعدادات كل مثيل على القرص من خلال تنفيذ أمر التصدير التالي:

    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، ولكنّها غير مطلوبة بشكل يومي إذا لم تنقل بياناتك إلى حِزم الدوال. يمكنك نقلها من مشروعك إلى أي موقع تخزين مناسب آخر إلى أن تحتاج إليها في المستقبل أو اختيار حذفها.