نقل بيانات إضافات Firebase إلى حِزم الدوال

يوضّح لك هذا الدليل كيفية نقل إضافاتك من بيئة Firebase Extensions المتوقّفة نهائيًا إلى حزمة دوال يمكنك تثبيتها ونشرها في قاعدة الرموز البرمجية الخاصة بك في Cloud Functions لـ Firebase (الجيل الثاني).

Firebase Extensions إدارة جميع جوانب إنشاء الإضافات وتعديلها وإزالتها. تجمع حِزم الدوال إمكانات الإضافات كدوال Cloud Functions for Firebase عادية من الجيل الثاني. بما أنّ حِزم الدوال هي Cloud Functions عادية، يمكنك إنشاؤها وتعديلها وحذفها وتحديد المشاكل فيها وحلّها باستخدام واجهة سطر الأوامر في Firebase ضمن مشروعك على Firebase. يساعدك هذا الدليل في الاستعداد لإدارة الدوال الآن واعتماد التحديثات فور توفّرها.

في هذا الدليل، يتم استخدام إضافة Stream Cloud Firestore to BigQuery (firestore-bigquery-export) كمثال يوضّح لك الأوامر ومخرجاتها لكل خطوة من خطوات نقل البيانات.

تحديد مسار نقل البيانات

تشجّع Firebase جميع ناشري Firebase Extensions على إنشاء بدائل لإضافاتهم كحِزم وظائف منشورة على npm. يمكنك التحقّق مما إذا كانت حزمة الدوال البديلة متاحة لإضافاتك بعدة طرق مختلفة:

  • انتقِل إلى صفحة "الإضافات" في وحدة تحكّم Firebase لمشروعك. تشير كل إضافة قمت بتثبيتها إلى ما إذا كان لديها بديل لمجموعة الوظائف متاح.

  • شغِّل firebase ext:list داخل مشروع Firebase في وحدة طرفية لعرض الإضافات المثبَّتة التي لها بدائل رسمية:

    firebase ext:list --project my-project

    i  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 الانتقال إلى حزمة دوال تم إنشاؤها ذاتيًا

Migrate to function kits on npm

التحقّق من القيود المعروفة لعملية نقل البيانات

قبل البدء في نقل بيانات نسخة من الإضافة، تحقَّق مما إذا كان الإعداد يستخدم أيًا من الميزات التالية التي تتطلب حلاً بديلاً أو غير متاحة بعد في حِزم الدوال:

  • تتطلّب مستودعات Docker المخصّصة ومفاتيح KMS حلاً يدويًا Cloud Functions for Firebase لا يتيح استخدام مَعلمات النظام البديلة لضبط مستودع Docker مخصّص أو مفتاح تشفير يديره العميل (مفتاح KMS). إذا كانت الإضافة تضبط أيًا من هاتين المَعلمتين، يُرجى الرجوع إلى الحل البديل في الأسئلة الشائعة.

قبل البدء

يجب إعداد واجهة سطر أوامر Firebase وبدء مشروع Firebase. عند استخدام واجهة سطر الأوامر، تأكَّد من استخدام الإصدار >= 15.32.0 من firebase-tools الذي يتضمّن أوامر نقل البيانات الجديدة ومجموعة الدوال.

أذونات وأدوار الحساب المطلوبة

استنادًا إلى ما يجب إنشاؤه وضبطه من خلال واجهة سطر الأوامر في Firebase أثناء عملية النقل، يجب أن يتضمّن الحساب المستخدَم للمصادقة مع Firebase وGoogle Cloud الأدوار التالية:

  • roles/firebaseextensions.editor
  • roles/cloudbuild.builds.editor
  • roles/artifactregistry.writer
  • roles/run.developer
  • roles/iam.serviceAccountUser
  • roles/iam.serviceAccountCreator
  • roles/cloudfunctions.admin (إذا كنت بحاجة إلى تنفيذ setIamPermissions لنقاط النهاية العامة)
  • ‫roles/secretmanager.admin (في حال استخدام مفاتيح سرية)
  • roles/serviceusage.serviceUsageAdmin (إذا كنت بحاجة إلى تفعيل واجهات برمجة تطبيقات جديدة)

ننصحك باستخدام حساب سبق أن ثبّت إضافات ونشر دوال، لأنّ معظم هذه الأذونات ستكون قد مُنحت له. إذا كان حساب نقل البيانات يحتاج إلى المزيد من الأدوار، اتّبِع تعليمات إدارة الهوية وإمكانية الوصول في Google Cloud لإضافتها.

اختيار سير عمل CLI

لنقل البيانات من مثيل إضافة إلى حزمة دوال متاحة على npm، حدِّد أحد الخيارات التالية:

  • (إجراء يُنصح به) نقل البيانات باستخدام أمر واجهة سطر الأوامر ext:migrate. ينشر هذا الأمر بديل حزمة الدوال قبل إلغاء تثبيت الإضافة التي يحل محلها.
  • نقل البيانات باستخدام أوامر واجهة سطر الأوامر (CLI) لحِزم الدوال يمكنك استخدام أوامر منفصلة لتحديث الإضافة، وتثبيت حزمة الدوال، وضبطها مثل الإضافة، ونشر الحزمة، وإلغاء تثبيت الإضافة. يوفّر ذلك مرونة أكبر لإعادة ترتيب الأوامر أو تنفيذ عمل إضافي بين الخطوات.

نقل البيانات باستخدام ext:migrate

مرة واحدة لكل مثيل إضافة، ابدأ عملية نقل البيانات من خلال تشغيل:

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

يرشدك هذا الأمر خلال:

  1. اختيار إضافة لنقلها تتوفّر لها حزمة وظائف رسمية بديلة
  2. اختيار مثيل محدّد لتلك الإضافة
  3. تحديث الإضافة إلى أحدث إصدار إذا لزم الأمر
  4. تثبيت حزمة الدوال وضبط مثيل بشكل مماثل لطريقة ضبط مثيل الإضافة
  5. جارٍ نشر حزمة الدوال.
  6. التحقّق من أنّ حزمة الوظائف تم تفعيلها بنجاح ومن أنّ جميع دوال مراحل النشاط، إن وُجدت، قد تم تشغيلها
  7. جارٍ إلغاء تثبيت نسخة الإضافة.

إذا كنت تعرف الإضافة المحدّدة أو نسخة الإضافة التي تريد نقلها، يمكنك تحديدها باستخدام علامات سطر الأوامر التالية:

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 to 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.

1. ترقية نسخة الإضافة إلى أحدث إصدار

يجب تحديث الإضافة إلى أحدث إصدار لتقليل الفرق بين نسخة الإضافة وحزمة الاستبدال. إذا لم تتم ترقية الإضافة، قد تحدث تغييرات كبيرة قد تؤدي إلى عطل بين نسخة الإضافة وبديلها في الحزمة. قد لا تتطابق الإعدادات التي تم تصديرها مع ما تتوقعه الحزمة بسبب تغييرات المَعلمات في الإصدارات المختلفة.

استخدِم أحد الخيارات التالية لتحديث الإضافة، حسب مكان تثبيتها:

  • من وحدة تحكّم Firebase
  • من واجهة سطر الأوامر (CLI) في Firebase باستخدام:
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

إذا تخطّيت هذه الخطوة، ستطلب منك واجهة سطر الأوامر الترقية عند تصدير الإعدادات إذا لم تكن الإضافة تستخدم أحدث إصدار.

2. مراجعة نسخة حزمة الدوال البديلة وتثبيتها

يمكنك تثبيت حزمة الدوال باستخدام أمر واجهة سطر الأوامر التالي:

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

3- ضبط مثيل حزمة الدوال بشكل مماثل للإضافة

يجب تخصيص نسخة الحزمة هذه بإعدادات مطابقة لإعدادات الإضافة التي يتم استبدالها. يمكنك تصدير إعدادات مثيل الإضافة إلى ملف .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>

4. نشر مجموعة الاستبدال والتحقّق منها

بعد تثبيت الحزمة وإتاحتها كمجموعة من الدوال، يمكنك نشر بديل الحزمة. تعمل حِزم الدوال مثل الدوال العادية، حيث تعمل كل نسخة من الحزمة كـ قاعدة رموز برمجية منفصلة لتنظيم الدوال. يمكنك اختيار نشر جميع الدوال أو مثيل حزمة معيّن فقط. أثناء نقل مثيل إضافة واحد، يجب نشر مثيل الحزمة هذا فقط.

إذا كانت حزمتك تستخدم أي مَعلمات جديدة لم تكن متوفّرة في مثيل الإضافة الذي نقلت منه، ستطلب منك واجهة سطر الأوامر في Firebase إدخالها في بداية عملية النشر. هذا ليس متوقعًا في هذا المثال العملي من إضافة 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 to 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                                                     │

5- إلغاء تثبيت الإضافة

بعد التحقّق من حزمة الدوال المنشورة، يمكنك إلغاء تثبيت الإضافة لتجنُّب تكرار سلوكها مرة للحزمة ومرة للإضافة. يمكنك إلغاء تثبيت جميع الإضافات من واجهة سطر الأوامر في Firebase بغض النظر عن طريقة تثبيتها، وذلك من خلال تمرير العلامة --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-testing
  • export-documents-production

إذا نقلت هذين المثيلَين من الإضافة إلى مثيلَين من حزمة الدوال في قاعدة رموز برمجية واحدة عند العمل باستخدام واجهة سطر الأوامر Firebase ونشرتهما باستخدام 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" أو تثبيت مثيل ثانٍ.