تثبيت "مجموعة أدوات المحاكاة المحلية" وإعدادها ودمجها

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

تثبيت مجموعة أدوات المحاكاة المحلية

قبل تثبيت حزمة المحاكي، ستحتاج إلى ما يلي:

  • الإصدار 16.0 من Node.js أو إصدار أحدث
  • الإصدار 11 من حزمة أدوات تطوير البرامج (JDK) من Java أو إصدار أحدث

لتثبيت حزمة المحاكيات:

  1. ثبِّت Firebase CLI. إذا لم يكن لديك Firebase CLI مثبّتًا، ثبِّته الآن. يجب توفُّر الإصدار 8.14.0 من واجهة برمجة التطبيقات أو إصدار أحدث لاستخدام حزمة المحاكيات. يمكنك التحقّق من الإصدار الذي تم تثبيته باستخدام الأمر التالي: 
    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 إلى إتلاف البيانات، فقبول الإعدادات التلقائية سيحافظ على إعدادات المحاكي الحالية.

ضبط المنفذ

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

محاكي المنفذ التلقائي
Authentication 9099
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5000
Pub/Sub 8085

إعداد رقم تعريف المشروع

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

من الممارسات الجيدة بشكل عام ضبط معرّف مشروع واحد لجميع عمليات بدء استخدام المحاكي، حتى تتمكّن Emulator Suite UI ومحاكيات المنتجات المختلفة وجميع المثيلات التي تعمل من محاكي معيّن من التواصل بشكل صحيح في جميع الحالات.

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

يمكنك التحقّق من بيانات تعريف المشروع بحثًا عن أي تناقضات في ما يلي:

  • المشروع التلقائي في سطر الأوامر: سيتم تلقائيًا استخدام رقم تعريف المشروع عند بدء التشغيل من المشروع الذي تم اختياره باستخدام firebase init أو firebase use. لعرض قائمة المشاريع (والاطّلاع على المشروع المحدّد) استخدِم firebase projects:list.
  • اختبارات وحدات القواعد غالبًا ما يتم تحديد رقم تعريف المشروع في طلبات الاتصال بأساليب مكتبة Rules Unit Testing‏ 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"
    }
  }
}

تحديد خيارات Java

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

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

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

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

تشغيل المحاكيات

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

الطلب الوصف
emulators:start ابدأ محاكيات لمنتجات 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= اختياري استخدِم المحاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for 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 اختياري استخدِم المحاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase. استورِد البيانات المحفوظة باستخدام خيار بدء التشغيل --export-on-exit أو الأمر emulators:export إلى مثيل محاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase قيد التشغيل. سيتم استبدال أي بيانات موجودة حاليًا في ذاكرة المحاكي.
emulators:exec scriptpath شغِّل النص البرمجي في scriptpath بعد بدء محاكيات لمنتجات Firebase التي تم ضبطها في firebase.json. ستتوقف عمليات المحاكي تلقائيًا عند انتهاء تنفيذ الرمز المبرمَج.
إبلاغ الوصف
--only اختياري يمكنك تحديد المحاكيات التي يتم تشغيلها. أدخِل قائمة مفصولة بفواصل بأسماء المحاكيات، مع تحديد اسم واحد أو أكثر من "firestore" أو "database" أو "functions" أو "hosting" أو "pubsub".
--inspect-functions debug_port اختياري استخدِم الوسيطة مع محاكي Cloud Functions لتفعيل تصحيح أخطاء نقاط التوقف للدوالّ على المنفذ المحدّد (أو المنفذ التلقائي 9229 في حال حذف الوسيطة). يُرجى العلم أنّه عند تقديم هذا العلامة، يتم تبديل محاكي Cloud Functions إلى وضع تنفيذ سلسلي خاص يتم فيه تنفيذ الدوال في عملية واحدة بترتيب تسلسلي (FIFO). ويؤدي ذلك إلى تبسيط تصحيح أخطاء الدوال، على الرغم من أنّ السلوك يختلف عن التنفيذ المتوازي لدوال متعددة العمليات في السحابة الإلكترونية.
--export-on-exit= اختياري استخدِم المحاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for 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 اختياري استخدِم المحاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase. استورِد البيانات المحفوظة باستخدام خيار بدء التشغيل --export-on-exit أو الأمر emulators:export إلى مثيل محاكي Authentication أو Cloud Firestore أو Realtime Database أو Cloud Storage for Firebase قيد التشغيل. سيتم استبدال أي بيانات موجودة حاليًا في ذاكرة المحاكي.
--ui اختياري تشغيل واجهة مستخدم المحاكي أثناء التنفيذ

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

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

يمكنك تصدير البيانات من محاكيات Authentication وCloud Firestore وRealtime Database و Cloud Storage for Firebase لاستخدامها كمجموعة بيانات مرجعية مشتركة وقابلة للمشاركة. يمكن استيراد مجموعات البيانات هذه باستخدام العلامة --import كما هو описан أعلاه.

emulators:export export_directory

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

يمكنك توجيه المحاكيات لتصدير البيانات تلقائيًا عند إيقافها باستخدام علامات --export-on-exit الموضّحة أعلاه.

الدمج مع نظام التطوير المتداخل (CI)

تشغيل صور مجموعة أدوات المحاكاة المُنشأة في حاويات

إنّ عملية تثبيت حزمة Emulator Suite وضبطها باستخدام الحاويات في أحد تصاميم عملية التكامل المستمر (CI) النموذجية هي عملية مباشرة.

في ما يلي بعض المشاكل التي يجب أخذها في الاعتبار:

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

    • ننصحك بإضافة هذا المسار إلى إعدادات ذاكرة التخزين المؤقت لإدارة الإصدارات لتجنُّب عمليات التنزيل المتكرّرة.

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

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

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

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

إذا كانت بيئة التطوير المتكامل (CI) تسمح لك بتحديد متغيّرات البيئة التي يمكن استخدامها في نصوص الترميز الخاصة بالإنشاء، ما عليك سوى إنشاء متغيّر بيئة يُسمى FIREBASE_TOKEN، مع القيمة التي هي سلسلة رمز الوصول. ستلتقط أداة Firebase CLI تلقائيًا متغيّر البيئة 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
  }
}

تفعيل / إيقاف عوامل تشغيل الدوالّ في الخلفية

في بعض الحالات، عليك إيقاف الدوالّ المحلية ومثبّتَي الإضافة مؤقتًا. على سبيل المثال، قد تحتاج إلى حذف جميع البيانات في emuCloud Firestorelator بدون تشغيل أي دوال 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) للمحاكي

تشير الجداول في هذا القسم إلى المحاكيات المتوافقة مع حِزم SDK العميل و"حِزم SDK للمشرف". تشير الحالة مستقبلية إلى أنّه من المخطَّط إتاحة المحاكي، ولكن ليس بعد.

توفّر حِزم تطوير البرامج (SDK) للعملاء

Android منصّات Apple الويب واجهة Firebase UI
Android 		واجهة مستخدم Firebase
iOS 		واجهة مستخدم Firebase
الويب
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 صيغة المستقبل لا ينطبق
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 صيغة المستقبل لا ينطبق
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 صيغة المستقبل 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 لا ينطبق
Cloud Functions 19.1.0 7.2.0 8.0.0 لا ينطبق غير متاح غير متاح
Hosting غير متاح غير متاح غير متاح غير متاح غير متاح غير متاح
Extensions غير متاح غير متاح غير متاح غير متاح غير متاح لا ينطبق

مدى توفّر حزمة SDK للمشرف

العقدة Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 صيغة المستقبل
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 صيغة المستقبل صيغة المستقبل صيغة المستقبل
Cloud Functions لا ينطبق غير متاح غير متاح غير متاح
Hosting غير متاح غير متاح غير متاح غير متاح
Extensions غير متاح غير متاح غير متاح لا ينطبق