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

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

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

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

  • Node.js بالإصدار 16.0 أو إصدار أحدث.
  • الإصدار 11 من Java JDK أو إصدار أحدث

لتثبيت "حزمة المحاكي"، يُرجى اتّباع الخطوات التالية:

  1. ثبِّت واجهة سطر الأوامر في Firebase. إذا لم يكن لديك واجهة سطر الأوامر في Firebase مثبّتة، يمكنك تثبيته الآن. ستحتاج إلى الإصدار 8.14.0 أو إصدار أحدث من واجهة سطر الأوامر لاستخدام "مجموعة أدوات المحاكاة". ويمكنك التحقّق من الإصدار المثبَّت باستخدام الأمر التالي: 
    firebase --version
  2. إذا لم يسبق لك إجراء ذلك، ابدأ في إعداد دليل العمل الحالي كمشروع Firebase، وذلك باتّباع التعليمات الظاهرة على الشاشة لتحديد المنتجات التي يجب استخدامها: 
    firebase init
  3. ابدأ إعداد "مجموعة أدوات المحاكاة". يؤدي هذا الأمر إلى بدء معالج إعداد يتيح لك اختيار المحاكيات المهمة وتنزيل الملفات الثنائية للمحاكي المقابلة وضبط منافذ المحاكي إذا لم تكن الإعدادات التلقائية مناسبة. 
    firebase init emulators

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

إعداد "مجموعة أدوات المحاكاة"

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

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

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

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

إعدادات المنفذ

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

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

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

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

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

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

يمكنك مراجعة بيانات أرقام تعريف المشروع بحثًا عن حالات عدم التطابق في:

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

تحقَّق أيضًا من إعدادات رقم تعريف المشروع الخاصة بالنظام الأساسي والتي ضبطتها أثناء ضبط مشاريع 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

يستند مُحاكي قاعدة البيانات في الوقت الفعلي ومحاكي 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.

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

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

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

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

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

يمكنك تصدير البيانات من أدوات محاكاة المصادقة وCloud Firestore وقاعدة البيانات في الوقت الفعلي وCloud Storage for Firebase لاستخدامها كمجموعة بيانات أساسية شائعة وقابلة للمشاركة. يمكن استيراد مجموعات البيانات هذه باستخدام علامة --import على النحو الموضَّح أعلاه.

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

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

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

الدمج مع نظام CI

تشغيل صور مجموعة المحاكيات المضمّنة في الحاوية

يُعد تثبيت مجموعة أدوات المحاكاة وإعدادها باستخدام حاويات ضمن إعداد 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

عرض قائمة بمحاكيات التشغيل

لإدراج أدوات المحاكاة قيد التشغيل حاليًا، أرسِل طلب GET إلى نقطة نهاية /emulators في "مركز المحاكي".

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 قيد التشغيل في دوال السحابة الإلكترونية أو في محاكيات الإضافات.

لإيقاف مشغِّلات الدوال المحلية مؤقتًا، يمكنك إرسال طلب PUT إلى نقطة النهاية /functions/disableBackgroundTriggers في Emulator Hub.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

لتفعيل مشغّلات الدوال المحلية بعد إيقافها، أرسِل طلب PUT إلى نقطة النهاية /functions/enableBackgroundTriggers في "مركز المحاكي".

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

عمليات دمج حزمة تطوير البرامج (SDK) للمحاكي

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

مدى توفّر حزمة تطوير البرامج (SDK) للعميل

Android أنظمة Apple الأساسية الويب واجهة مستخدم Firebase
Android 		واجهة مستخدم Firebase
iOS 		واجهة مستخدم Firebase
الويب
قاعدة بيانات الوقت الفعلي 19.4 7.2.0 8.0.0 6.4 صيغة المستقبل لا ينطبق
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4 صيغة المستقبل لا ينطبق
المصادقة 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) للمشرف

العقدة Java Python انتقال
قاعدة بيانات الوقت الفعلي 8.6.0 6.10.0 2.18 صيغة المستقبل
Cloud Firestore 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 صيغة المستقبل صيغة المستقبل صيغة المستقبل
وظائف السحابة الإلكترونية لا ينطبق غير متاح غير متاح لا ينطبق
الاستضافة لا ينطبق غير متاح غير متاح لا ينطبق
الإضافات لا ينطبق غير متاح غير متاح لا ينطبق