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

يمكن تثبيت "مجموعة أدوات المحاكاة المحلية" من 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 مع توفير أمان البيانات المفتوحة.

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

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

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

استنادًا إلى طريقة استدعاء المحاكيات، يمكنك تشغيل عدة مثيلات من المحاكي باستخدام أرقام تعريف مختلفة لمشاريع 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.

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

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

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

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

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

التكامل مع نظام التكامل المستمر

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

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

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

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

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

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

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

إذا كانت مهام سير العمل الخاصة بالتكامل المستمر تعتمد على Firebase Hosting، عليك تسجيل الدخول باستخدام رمز مميّز لتشغيل firebase 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) للعميل

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