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

يمكن تثبيت "مجموعة أدوات المحاكاة المحلية لـ 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 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.
  • اختبارات وحدات القواعد غالبًا ما يتم تحديد رقم تعريف المشروع في طلبات استدعاء طرق مكتبة اختبار وحدة القواعد initializeTestEnvironment أو initializeTestApp.
  • علامة سطر الأوامر --project يؤدي تمرير علامة واجهة سطر الأوامر Firebase --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 إلى وضع تنفيذ تسلسلي خاص يتم فيه تنفيذ الدوال في عملية واحدة، بترتيب تسلسلي (الوارد أولاً يُباع أولاً)؛ يسهّل ذلك تصحيح أخطاء الدوال، على الرغم من أنّ السلوك يختلف عن التنفيذ المتوازي للدوال في السحابة الإلكترونية.
--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 PATH/TO/SCRIPT

يجب تشغيل النص البرمجي في PATH/TO/SCRIPT بعد بدء تشغيل المحاكيات لمنتجات Firebase التي تم ضبطها في firebase.json. وستتوقف عمليات المحاكي تلقائيًا عند انتهاء تشغيل النص البرمجي.

إبلاغ الوصف
--only اختياري: يمكنك تحديد المحاكيات التي يتم تشغيلها. أدخِل قائمة بأسماء المحاكيات مفصولة بفواصل، مع تحديد واحد أو أكثر مما يلي: firestore أو database أو functions أو hosting أو pubsub.
--inspect-functions DEBUG_PORT اختياري: يُستخدَم مع محاكي Cloud Functions لتفعيل تصحيح أخطاء الدوال عند نقطة التوقف في المنفذ المحدّد (أو المنفذ التلقائي 9229 في حال حذف الوسيطة). يُرجى العِلم أنّه عند توفير هذه العلامة، ينتقل محاكي Cloud Functions إلى وضع تنفيذ تسلسلي خاص يتم فيه تنفيذ الدوال في عملية واحدة، بترتيب تسلسلي (الوارد أولاً يُباع أولاً)؛ يسهّل ذلك تصحيح أخطاء الدوال، على الرغم من أنّ السلوك يختلف عن تنفيذ الدوال المتعدّد العمليات والمتوازي في السحابة الإلكترونية.
--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 الموضّحة أعلاه.

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

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

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

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

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

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

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

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

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

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

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

استخدام واجهة برمجة التطبيقات REST API لـ Emulator Hub

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

لإدراج المحاكيات قيد التشغيل حاليًا، أرسِل طلب 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) للمحاكي

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

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

Android منصات Apple الويب Firebase UI
Android
Firebase UI
iOS
Firebase UI
Web
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 غير متاح غير متاح غير متاح غير متاح غير متاح لا ينطبق

توفُّر Admin 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 غير متاح غير متاح غير متاح لا ينطبق