تثبيت وتكوين ودمج Local Emulator Suite

يمكن تثبيت Firebase Local Emulator Suite وتكوينه ليناسب نماذج أولية وبيئات اختبار مختلفة، بدءًا من جلسات النماذج الأولية لمرة واحدة وحتى سير عمل التكامل المستمر على مستوى الإنتاج.

قم بتثبيت جناح المحاكي المحلي

قبل تثبيت Emulator Suite، ستحتاج إلى:

• Node.js الإصدار 16.0 أو أعلى.
• جافا JDK الإصدار 11 أو أعلى.

لتثبيت جناح المحاكي:

1. قم بتثبيت Firebase CLI . إذا لم تكن واجهة سطر أوامر Firebase مثبتة لديك بالفعل، فقم بتثبيتها الآن . ستحتاج إلى إصدار CLI 8.14.0 أو أعلى لاستخدام Emulator Suite. يمكنك التحقق من الإصدار الذي قمت بتثبيته باستخدام الأمر التالي:

   firebase --version

2. إذا لم تكن قد قمت بذلك بالفعل، فقم بتهيئة دليل العمل الحالي كمشروع Firebase، باتباع المطالبات التي تظهر على الشاشة لتحديد المنتجات التي تريد استخدامها:

   firebase init

3. قم بإعداد جناح المحاكي. يبدأ هذا الأمر معالج التكوين الذي يتيح لك تحديد المحاكيات التي تهمك، وتنزيل ملفات المحاكي الثنائية المقابلة، وتعيين منافذ المحاكي إذا كانت الإعدادات الافتراضية غير مناسبة.

   firebase init emulators

بمجرد تثبيت المحاكي، لن يتم إجراء أي عمليات فحص للتحديث ولن تحدث أي تنزيلات تلقائية إضافية حتى تقوم بتحديث إصدار Firebase CLI الخاص بك.

تكوين جناح المحاكي

يمكنك اختياريًا تكوين منافذ شبكة المحاكيات والمسار إلى تعريفات قواعد الأمان في ملف firebase.json :

• قم بتغيير منافذ المحاكي عن طريق تشغيل firebase init emulators أو عن طريق تحرير firebase.json يدويًا.
• قم بتغيير المسار إلى تعريفات قواعد الأمان عن طريق تحرير firebase.json يدويًا.

إذا لم تقم بتكوين هذه الإعدادات، فستستمع المحاكيات على منافذها الافتراضية، وسيتم تشغيل Cloud Firestore وRealtime Database وCloud Storage for Firebase مع أمان البيانات المفتوحة.

يأمر	وصف
محاكيات init	بدء تشغيل معالج تهيئة المحاكي. حدد المحاكيات المطلوب تثبيتها وحدد إعدادات منفذ المحاكي بشكل اختياري. init emulators غير مدمرة؛ سيؤدي قبول الإعدادات الافتراضية إلى الحفاظ على تكوين المحاكي الحالي.

تكوين المنفذ

يرتبط كل محاكي بمنفذ مختلف على جهازك بقيمة افتراضية مفضلة.

محاكي	المنفذ الافتراضي
المصادقة	9099
واجهة المستخدم لجناح المحاكي	4000
وظائف السحابة	5001
إيفينتارك	9299
قاعدة بيانات الوقت الحقيقي	9000
سحابة فايرستور	8080
التخزين السحابي لـ Firebase	9199
استضافة Firebase	5000
حانة/فرعية	8085

تكوين معرف المشروع

اعتمادًا على كيفية استدعاء المحاكيات، يمكنك تشغيل مثيلات متعددة لمحاكي باستخدام معرفات مشروع Firebase مختلفة أو مثيلات محاكي متعددة لمعرف مشروع معين. في مثل هذه الحالات، يتم تشغيل مثيلات المحاكي في بيئة منفصلة.

من الممارسات الجيدة بشكل عام تعيين معرف مشروع واحد لجميع استدعاءات المحاكي، بحيث يمكن لواجهة مستخدم Emulator Suite ومحاكيات المنتجات المختلفة وجميع المثيلات قيد التشغيل لمحاكي معين التواصل بشكل صحيح في جميع الحالات.

يُصدر Local Emulator Suite تحذيرات عندما يكتشف معرفات مشاريع متعددة في البيئة، على الرغم من أنه يمكنك تجاوز هذا السلوك عن طريق تعيين مفتاح singleProjectMode على false في firebase.json الخاص بك.

يمكنك التحقق من إعلان (إعلانات) معرف المشروع بحثًا عن عدم التطابق في:

• المشروع الافتراضي في سطر الأوامر. افتراضيًا، سيتم الحصول على معرف المشروع عند بدء التشغيل من المشروع المحدد باستخدام firebase init أو firebase use . لعرض قائمة المشاريع (ورؤية المشروع الذي تم تحديده) استخدم firebase projects:list .
• اختبارات وحدة القواعد. غالبًا ما يتم تحديد معرف المشروع في الاستدعاءات إلى أساليب مكتبة اختبار وحدة القواعد initializeTestEnvironment أو initializeTestApp .
• سطر الأوامر --project علامة المشروع. يؤدي تمرير علامة Firebase CLI --project إلى تجاوز المشروع الافتراضي. ستحتاج إلى التأكد من تطابق قيمة العلامة مع معرف المشروع في اختبارات الوحدة وتهيئة التطبيق.

تحقق أيضًا من تكوينات معرف المشروع الخاصة بالنظام الأساسي التي قمت بتعيينها أثناء تكوين أنظمة Apple و Android ومشروعات الويب .

تكوين قواعد الأمان

ستأخذ المحاكيات تكوين قواعد الأمان من database firestore ومفاتيح تكوين storage في firebase.json .

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

تحديد خيارات جافا

يعتمد محاكي Realtime Database ومحاكي Cloud Firestore وجزء من Cloud Storage لمحاكي Firebase على Java، والتي يمكن تخصيصها باستخدام علامات JVM عبر متغير البيئة JAVA_TOOL_OPTIONS .

على سبيل المثال، إذا واجهت أخطاء متعلقة بمساحة كومة Java المؤقتة، فيمكنك زيادة الحد الأقصى لحجم كومة Java المؤقتة إلى 4 جيجابايت:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

يمكن تحديد أعلام متعددة بين علامات اقتباس مفصولة بمسافات، مثل JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" . تؤثر العلامات فقط على مكونات المحاكيات المستندة إلى Java وليس لها أي تأثير على الأجزاء الأخرى من Firebase CLI، مثل Emulator Suite UI.

بدء تشغيل المحاكيات

يمكنك بدء تشغيل المحاكيات حتى يتم إنهاؤها يدويًا، أو تشغيلها لمدة برنامج نصي اختباري محدد ثم إيقاف تشغيلها تلقائيًا.

يأمر	وصف
المحاكيات:ابدأ	ابدأ تشغيل برامج محاكاة لمنتجات Firebase التي تم تكوينها في firebase.json . ستستمر عمليات المحاكي في العمل حتى تتوقف بشكل صريح. سيؤدي استدعاء emulators:start إلى تنزيل المحاكيات إلى ~/.cache/firebase/emulators/ إذا لم تكن مثبتة بالفعل. علَم وصف --only خياري. تحديد المحاكيات التي تبدأ. قم بتوفير قائمة مفصولة بفواصل بأسماء المحاكيات، مع تحديد واحد أو أكثر من "auth" أو "database" أو "firestore" أو "functions" أو "hosting" أو "pubsub". --inspect-functions debug_port خياري. استخدمه مع محاكي Cloud Functions لتمكين تصحيح أخطاء نقاط التوقف للوظائف في المنفذ المحدد (أو المنفذ الافتراضي 9229 إذا تم حذف الوسيطة). لاحظ أنه عند توفير هذه العلامة، يتحول محاكي Cloud Functions إلى وضع تنفيذ متسلسل خاص يتم فيه تنفيذ الوظائف في عملية واحدة، بترتيب تسلسلي (FIFO)؛ وهذا يبسط تصحيح أخطاء الوظائف، على الرغم من أن السلوك يختلف عن التنفيذ المتوازي متعدد العمليات للوظائف في السحابة. --export-on-exit= خياري. استخدمه مع المصادقة أو Cloud Firestore أو Realtime Database أو Cloud Storage لمحاكي Firebase. قم بتوجيه المحاكي (المضاهاة) لتصدير البيانات إلى دليل عند حدوث إيقاف التشغيل، كما هو موضح emulators:export . يمكن تحديد دليل التصدير باستخدام هذه العلامة: firebase emulators:start --export-on-exit=./saved-data . إذا تم استخدام --import ، فإن مسار التصدير الافتراضي هو نفسه؛ على سبيل المثال: firebase emulators:start --import=./data-path --export-on-exit . وأخيرًا، إذا رغبت في ذلك، قم بتمرير مسارات دليل مختلفة إلى علامتي --import و --export-on-exit . --import= import_directory خياري. استخدمه مع المصادقة أو Cloud Firestore أو Realtime Database أو Cloud Storage لمحاكي Firebase. قم باستيراد البيانات المحفوظة باستخدام خيار بدء التشغيل --export-on-exit أو emulators:export إلى مثيل Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase قيد التشغيل. سيتم الكتابة فوق أي بيانات موجودة حاليًا في ذاكرة المحاكي.
المحاكيات: scriptpath exec	قم بتشغيل البرنامج النصي في scriptpath بعد بدء المحاكيات لمنتجات Firebase التي تم تكوينها في firebase.json . ستتوقف عمليات المحاكي تلقائيًا عند انتهاء تشغيل البرنامج النصي. علَم وصف --only خياري. تحديد المحاكيات التي تبدأ. قم بتوفير قائمة مفصولة بفواصل بأسماء المحاكيات، مع تحديد واحد أو أكثر من "firestore" أو "قاعدة البيانات" أو "الوظائف" أو "hosting" أو "pubsub". --inspect-functions debug_port خياري. استخدمه مع محاكي Cloud Functions لتمكين تصحيح أخطاء نقاط التوقف للوظائف في المنفذ المحدد (أو المنفذ الافتراضي 9229 إذا تم حذف الوسيطة). لاحظ أنه عند توفير هذه العلامة، يتحول محاكي Cloud Functions إلى وضع تنفيذ متسلسل خاص يتم فيه تنفيذ الوظائف في عملية واحدة، بترتيب تسلسلي (FIFO)؛ وهذا يبسط تصحيح أخطاء الوظائف، على الرغم من أن السلوك يختلف عن التنفيذ المتوازي متعدد العمليات للوظائف في السحابة. --export-on-exit= خياري. استخدمه مع المصادقة أو Cloud Firestore أو Realtime Database أو Cloud Storage لمحاكي Firebase. قم بتوجيه المحاكي (المضاهاة) لتصدير البيانات إلى دليل عند حدوث إيقاف التشغيل، كما هو موضح emulators:export . يمكن تحديد دليل التصدير باستخدام هذه العلامة: firebase emulators:start --export-on-exit=./saved-data . إذا تم استخدام --import ، فإن مسار التصدير الافتراضي هو نفسه؛ على سبيل المثال: firebase emulators:start --import=./data-path --export-on-exit . وأخيرًا، إذا رغبت في ذلك، قم بتمرير مسارات دليل مختلفة إلى علامتي --import و --export-on-exit . --import= import_directory خياري. استخدمه مع المصادقة أو Cloud Firestore أو Realtime Database أو Cloud Storage لمحاكي Firebase. قم باستيراد البيانات المحفوظة باستخدام خيار بدء التشغيل --export-on-exit أو emulators:export إلى مثيل Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase قيد التشغيل. سيتم الكتابة فوق أي بيانات موجودة حاليًا في ذاكرة المحاكي. --ui خياري. قم بتشغيل Emulator UI أثناء التنفيذ.

تُعد طريقة firebase emulators:exec بشكل عام أكثر ملاءمة لسير عمل التكامل المستمر.

تصدير واستيراد بيانات المحاكي

يمكنك تصدير البيانات من Authentication وCloud Firestore وRealtime Database وCloud Storage لمحاكيات Firebase لاستخدامها كمجموعة بيانات أساسية مشتركة وقابلة للمشاركة. يمكن استيراد مجموعات البيانات هذه باستخدام علامة --import ، كما هو موضح أعلاه.

المحاكيات: تصدير export_directory

المصادقة أو Cloud Firestore أو قاعدة بيانات Realtime أو التخزين السحابي لمحاكي Firebase . تصدير البيانات من Cloud Firestore أو Realtime Database أو Cloud Storage لمثيل محاكي Firebase قيد التشغيل. سيتم إنشاء export_directory المحدد إذا لم يكن موجودًا بالفعل. في حالة وجود الدليل المحدد، سيُطلب منك تأكيد ضرورة الكتابة فوق بيانات التصدير السابقة. يمكنك تخطي هذه المطالبة باستخدام علامة --force . يحتوي دليل التصدير على ملف بيان البيانات، firebase-export-metadata.json . يمكنك توجيه المحاكيات لتصدير البيانات تلقائيًا عند إيقاف تشغيلها باستخدام علامات --export-on-exit الموضحة أعلاه.

التكامل مع نظام CI الخاص بك

تشغيل صور Emulator Suite المعبأة في حاوية

يعد تثبيت Emulator Suite وتكوينه مع الحاويات في إعداد CI النموذجي أمرًا بسيطًا.

هناك بعض القضايا التي يجب ملاحظتها:

• يتم تثبيت ملفات JAR وتخزينها مؤقتًا في ~/.cache/firebase/emulators/ .

  • قد ترغب في إضافة هذا المسار إلى تكوين ذاكرة التخزين المؤقت لـ CI لتجنب التنزيلات المتكررة.

• إذا لم يكن لديك ملف firebase.json في المستودع الخاص بك، فيجب عليك إضافة وسيطة سطر أوامر إلى الأمر emulators:start أو emulators:exec لتحديد المحاكيات التي يجب تشغيلها. على سبيل المثال،
  --only functions,firestore .

إنشاء رمز مميز للمصادقة (محاكي الاستضافة فقط)

إذا كانت مسارات عمل التكامل المستمر لديك تعتمد على استضافة Firebase، فستحتاج إلى تسجيل الدخول باستخدام رمز مميز لتشغيل firebase emulators:exec . لا تتطلب المحاكيات الأخرى تسجيل الدخول.

لإنشاء رمز مميز، قم بتشغيل firebase login:ci على بيئتك المحلية؛ لا ينبغي أن يتم تنفيذ هذا من نظام CI. اتبع التعليمات للمصادقة. يجب أن تحتاج إلى تنفيذ هذه الخطوة مرة واحدة فقط لكل مشروع، نظرًا لأن الرمز المميز سيكون صالحًا عبر الإصدارات. يجب التعامل مع الرمز المميز ككلمة مرور؛ تأكد من الحفاظ على سرية الأمر.

إذا كانت بيئة CI الخاصة بك تسمح لك بتحديد متغيرات البيئة التي يمكن استخدامها في البرامج النصية للإنشاء، فما عليك سوى إنشاء متغير بيئة يسمى FIREBASE_TOKEN ، حيث تكون القيمة هي سلسلة رمز الوصول. سوف تلتقط واجهة سطر أوامر Firebase تلقائيًا متغير البيئة FIREBASE_TOKEN وستبدأ المحاكيات بشكل صحيح.

كملاذ أخير، يمكنك ببساطة تضمين الرمز المميز في البرنامج النصي للبناء الخاص بك، ولكن تأكد من عدم وصول الأطراف غير الموثوق بها. بالنسبة لهذا الأسلوب المضمن، يمكنك إضافة --token "YOUR_TOKEN_STRING_HERE" إلى أمر firebase emulators:exec .

استخدم Emulator Hub REST API

قائمة المحاكيات قيد التشغيل

لسرد المحاكيات قيد التشغيل حاليًا، أرسل طلب GET إلى نقطة النهاية /emulators الخاصة بـ Emulator Hub.

curl localhost:4400/emulators

ستكون النتيجة كائن JSON يسرد جميع المحاكيات قيد التشغيل وتكوين المضيف/المنفذ الخاص بها، على سبيل المثال:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

تمكين / تعطيل مشغلات وظيفة الخلفية

في بعض المواقف، ستحتاج إلى تعطيل الوظائف المحلية ومشغلات الإضافات مؤقتًا. على سبيل المثال، قد ترغب في حذف جميع البيانات الموجودة في محاكي Cloud Firestore دون تشغيل أي وظائف onDelete التي تعمل في محاكيات Cloud Functions أو Extensions.

لتعطيل مشغلات الوظائف المحلية مؤقتًا، أرسل طلب PUT إلى نقطة النهاية /functions/disableBackgroundTriggers الخاصة بـ Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

ستكون النتيجة كائن JSON يعرض بالتفصيل الحالة الحالية.

{
  "enabled": false
}

لتمكين مشغلات الوظائف المحلية بعد تعطيلها، أرسل طلب PUT إلى نقطة النهاية /functions/enableBackgroundTriggers في Emulator Hub.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

ستكون النتيجة كائن JSON يعرض بالتفصيل الحالة الحالية.

{
  "enabled": true
}

تكاملات محاكي SDK

تشير الجداول الموجودة في هذا القسم إلى المحاكيات التي يدعمها العميل والمشرف SDKs. المستقبل يعني أنه تم التخطيط لدعم المحاكي ولكنه غير متوفر بعد.

توفر SDK للعميل

	ذكري المظهر	منصات أبل	ويب	واجهة مستخدم Firebase ذكري المظهر	واجهة مستخدم Firebase دائرة الرقابة الداخلية	واجهة مستخدم Firebase ويب
قاعدة بيانات الوقت الحقيقي	19.4.0	7.2.0	8.0.0	6.4.0	مستقبل	لا يوجد
سحابة فايرستور	21.6.0	7.2.0	8.0.0	6.4.0	مستقبل	لا يوجد
المصادقة	20.0.0	7.0.0	8.0.0	7.0.0	مستقبل	4.7.2
التخزين السحابي لـ Firebase	20.0.0	8.0.0	8.4.0	7.0.0	11.0.0	لا يوجد
وظائف السحابة	19.1.0	7.2.0	8.0.0	لا يوجد	لا يوجد	لا يوجد
الاستضافة	لا يوجد	لا يوجد	لا يوجد	لا يوجد	لا يوجد	لا يوجد
ملحقات	لا يوجد	لا يوجد	لا يوجد	لا يوجد	لا يوجد	لا يوجد

توفر SDK للمشرف

	العقدة	جافا	بايثون	يذهب
قاعدة بيانات الوقت الحقيقي	8.6.0	6.10.0	2.18.0	مستقبل
سحابة فايرستور	8.0.0	6.10.0	3.0.0	1.0.0
المصادقة	9.3.0	7.2.0	5.0.0	4.2.0
التخزين السحابي لـ Firebase	9.8.0	مستقبل	مستقبل	مستقبل
وظائف السحابة	لا يوجد	لا يوجد	لا يوجد	لا يوجد
الاستضافة	لا يوجد	لا يوجد	لا يوجد	لا يوجد
ملحقات	لا يوجد	لا يوجد	لا يوجد	لا يوجد