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

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

ضبط المنفذ

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

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

استنادًا إلى كيفية استدعاء المحاكيات، يمكنك تشغيل عدّة نُسخ من أحد المحاكيات باستخدام أرقام تعريف مشاريع مختلفة على 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 كما هو описан أعلاه.

الدمج مع نظام التطوير المتداخل (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) للعملاء

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