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

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

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

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

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

لتثبيت Emulator Suite، اتّبِع الخطوات التالية:

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

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

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

المحاكي	المنفذ التلقائي
Authentication	9099
App Hosting	5002
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. ستستمر عمليات المحاكي في العمل إلى أن يتم إيقافها بشكلٍ صريح. سيؤدي تنفيذ الأمر Calling 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 سيتم استبدال أي بيانات مخزّنة حاليًا في ذاكرة المحاكي. --log-verbosity=verbosity اختياري. يقلّل هذا الخيار من مقدار ناتج التسجيل من المحاكيات لتقليل التشويش في وحدة التحكّم وفي ملفات السجلّ. القيم الصالحة هي DEBUG وINFO وQUIET وSILENT.
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 اختياري. تشغيل واجهة مستخدم المحاكي أثناء التنفيذ --log-verbosity=verbosity اختياري. يقلّل هذا الخيار من مقدار ناتج التسجيل من المحاكيات للحدّ من التشويش في وحدة التحكّم وفي ملفات السجلّ. القيم الصالحة هي DEBUG وINFO وQUIET وSILENT.

تكون الطريقة 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 الموضّحة أعلاه.

التكامل مع نظام الدمج المتواصل

تشغيل صور "مجموعة أدوات المحاكاة" المستندة إلى الحاويات

تتسم عملية تثبيت Emulator Suite وضبطه باستخدام الحاويات في عملية إعداد نموذجية لعملية الدمج المتواصل بالبساطة.

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

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

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

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

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

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

ملاحظة: إذا كنت قد أعددت الاستضافة في firebase.json ولكنك لا تحتاج إليها في عمليات إعداد اختبار التكامل المستمر، استخدِم العلامة --only لتحديد emulators:start أو emulators:exec لتضمين المحاكيات التي تحتاج إليها فقط.

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

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

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

توفُّر حِزمة تطوير البرامج (SDK) الخاصة بالعميل

	Android	منصات Apple	الويب	Firebase UI Android	‫Firebase UI iOS	‫Firebase UI الويب
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 للمشرف

	Node	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	غير متاح	غير متاح	غير متاح	لا ينطبق