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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

تفعيل / إيقاف عوامل تشغيل الدوالّ في الخلفية

في بعض الحالات، عليك إيقاف الدوالّ المحلية ومثبّتَي الإضافة مؤقتًا. على سبيل المثال، قد تحتاج إلى حذف جميع البيانات في محاكي 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) للعملاء

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