ربط تطبيقك بمحاكي Cloud Firestore

قبل ربط تطبيقك بمحاكي Cloud Firestore، احرص على فهم سير العمل العام لحزمة Firebase Local Emulator Suite، وتثبيت وإعداد مجموعة Local Emulator Suite، ومراجعة أوامر واجهة سطر الأوامر.

اختيار مشروع في Firebase

تحاكي "حزمة محاكي Firebase المحلي" المنتجات في مشروع واحد على Firebase.

لاختيار المشروع المطلوب استخدامه، قبل بدء تشغيل أدوات المحاكاة، عليك تشغيل واجهة سطر الأوامر firebase use في دليل العمل. أو يمكنك تمرير علامة --project إلى كل أمر محاكي.

تتيح "مجموعة أدوات المحاكاة المحلية" محاكاة مشاريع Firebase الحقيقية ومشاريع الإصدار التجريبي.

نوع المشروع الميزات الاستخدام مع المحاكيات
حقيقية

مشروع Firebase الحقيقي هو المشروع الذي أنشأته وضبطته (على الأرجح من خلال وحدة تحكُّم Firebase).

تتضمّن المشاريع الحقيقية موارد مباشرة، مثل مثيلات قاعدة البيانات أو حِزم التخزين أو الدوال أو أي مورد آخر يتم إعداده لهذا المشروع على Firebase.

عند العمل مع مشاريع Firebase، يمكنك تشغيل محاكيات لأي من المنتجات المتوافقة أو لجميع المنتجات.

بالنسبة إلى أي منتجات لا تحاكيها، ستتفاعل تطبيقاتك ورمزك مع المورد المباشر (مثال قاعدة البيانات أو حزمة التخزين أو الوظيفة وما إلى ذلك).

الخصائص الديموغرافية

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

تتضمّن أرقام تعريف المشاريع للمشاريع التجريبية البادئة demo-.

عند العمل على مشاريع Firebase التجريبية، تتفاعل تطبيقاتك ورموزك مع المحاكيات فقط. إذا حاول تطبيقك التفاعل مع مورد لا يعمل محاكي له، لن ينجح هذا الرمز.

ننصحك باستخدام المشاريع التجريبية كلّما أمكن ذلك. تشمل المزايا ما يلي:

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

استخدام تطبيقك للتفاعل مع المحاكيات

عند بدء التشغيل، ينشئ محاكي Cloud Firestore قاعدة بيانات تلقائية وقاعدة بيانات مُسمّاة لكل إعدادات firestore في ملف firebase.json.

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

لاستخدام قواعد البيانات التلقائية والمسمّاة بشكل تفاعلي في واجهة مستخدم حزمة أداة المحاكاة، عليك تعديل عنوان URL في شريط العناوين في المتصفّح لاختيار إما قاعدة البيانات التلقائية أو قاعدة البيانات المسماة.

  • على سبيل المثال، لتصفّح البيانات في المثيل التلقائي، عدِّل عنوان URL إلى localhost:4000/firestore/default/data.
  • للتصفّح في مثيل باسم ecommerce، يجب التحديث إلى localhost:4000/firestore/ecommerce/data.

أنظمة Android الأساسية وأنظمة Apple وحِزم تطوير البرامج (SDK) على الويب

يمكنك إعداد الإعدادات داخل التطبيق أو صفوف الاختبار للتفاعل مع Cloud Firestore على النحو التالي. لاحظ أنه في النماذج التالية، يتم ربط رمز التطبيق بقاعدة بيانات المشروع الافتراضية. للحصول على أمثلة تتضمن قواعد بيانات إضافية في Cloud Firestore خارج قاعدة البيانات التلقائية، راجع دليل قواعد البيانات المتعددة.

Kotlin+KTX
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
val firestore = Firebase.firestore
firestore.useEmulator("10.0.2.2", 8080)

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}
Java
// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

واجهة برمجة تطبيقات الويب النموذجية

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, '127.0.0.1', 8080);

واجهة برمجة تطبيقات مساحات الاسم على الويب

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("127.0.0.1", 8080);
}

ليس هناك حاجة إلى إعداد إضافي لاختبار دوال السحابة التي يتم تشغيلها بواسطة أحداث Firestore باستخدام المحاكي. عند تشغيل محاكيَي Firestore وCloud Functions، ستعملان معًا تلقائيًا.

حِزم SDK للمشرف

يتم ربط حِزم SDK لمشرف Firebase تلقائيًا بمحاكي Cloud Firestore عند ضبط متغير بيئة FIRESTORE_EMULATOR_HOST:

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

إذا كان الرمز قيد التشغيل داخل محاكي دوال السحابة الإلكترونية، سيتم ضبط رقم تعريف المشروع وغيره من الإعدادات تلقائيًا عند طلب initializeApp.

إذا كنت تريد ربط رمز SDK للمشرف بمحاكي مشترك يتم تشغيله في بيئة أخرى، عليك تحديد رقم تعريف المشروع نفسه الذي أعددته باستخدام واجهة سطر الأوامر في Firebase. يمكنك تمرير رقم تعريف المشروع إلى "initializeApp" مباشرةً أو ضبط متغيّر بيئة GCLOUD_PROJECT.

SDK لمشرف Node.js
admin.initializeApp({ projectId: "your-project-id" });
متغيّر البيئة
export GCLOUD_PROJECT="your-project-id"

محو قاعدة البيانات بين الاختبارات

لا يوفّر Production Firestore طريقة لحزمة تطوير البرامج (SDK) لنظام التشغيل الأساسي من أجل مسح قاعدة البيانات، ولكن يمنحك محاكي Firestore نقطة نهاية REST تحديدًا لهذا الغرض، والتي يمكن طلبها من خلال إعداد إطار عمل الاختبار أو خطوة تقسيم للأسفل أو من فئة اختبار أو من واجهة الأوامر (مثلاً، من خلال curl) قبل بدء الاختبار. يمكنك استخدام هذه الطريقة كبديل لإيقاف عملية المحاكي.

وبطريقة مناسبة، نفِّذ عملية HTTP DELETE مع تزويد رقم تعريف مشروع Firebase، على سبيل المثال firestore-emulator-example، في نقطة النهاية التالية:

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

بطبيعة الحال، من المفترض أن يكون الرمز الخاص بك بانتظار تأكيد REST بأنّه تم الانتهاء من عملية المسح أو فشلها.

يمكنك إجراء هذه العملية من واجهة الأوامر:

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

بعد تنفيذ خطوة كهذه، يمكنك تسلسل اختباراتك وتشغيل الدوال بثقة أنّه ستتم إزالة البيانات القديمة نهائيًا بين عمليات التشغيل وأنّك تستخدم إعدادات اختبار أساسية جديدة.

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

تسمح لك قاعدة البيانات وCloud Storage لمحاكيات Firebase بتصدير البيانات من مثيل المحاكي قيد التشغيل. حدِّد مجموعة أساسية من البيانات لاستخدامها في اختبارات الوحدات أو عمليات سير عمل الدمج المستمر، ثم صدِّرها لمشاركتها مع الفريق.

firebase emulators:export ./dir

في الاختبارات، عند بدء تشغيل المحاكي، استورِد البيانات الأساسية.

firebase emulators:start --import=./dir

يمكنك أن تطلب من المحاكي تصدير البيانات عند إيقاف التشغيل، إما من خلال تحديد مسار تصدير أو استخدام المسار الذي تم تمريره إلى العلامة --import.

firebase emulators:start --import=./dir --export-on-exit

تعمل خيارات استيراد البيانات وتصديرها مع الأمر firebase emulators:exec أيضًا. لمزيد من المعلومات، يمكنك الرجوع إلى مرجع أوامر المحاكي.

عرض نشاط قواعد الأمان

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

استخدام أداة مراقبة الطلبات

يتيح لك محاكي Cloud Firestore عرض طلبات العملاء في واجهة مستخدم Emulator Suite، بما في ذلك تتبّع تقييم قواعد أمان Firebase.

افتح علامة التبويب Firestore > الطلبات لعرض تسلسل التقييم التفصيلي لكل طلب.

أداة مراقبة طلبات محاكي Firestore تعرض تقييمات قواعد الأمان

عرض تقارير تقييمات القواعد بشكل مرئي

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

بعد إجراء مجموعة من الاختبارات، يمكنك الوصول إلى تقارير "تغطية الاختبارات" التي توضح كيفية تقييم كل قاعدة من قواعد الأمان.

وللحصول على التقارير، يمكنك طلب بحث عن نقطة نهاية مكشوفة على المحاكي أثناء تشغيله. للحصول على إصدار متوافق مع المتصفّح، استخدِم عنوان URL التالي:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

يؤدي هذا إلى تقسيم القواعد إلى تعبيرات وتعبيرات فرعية يمكنك تمرير الماوس فوقها للحصول على مزيد من المعلومات، بما في ذلك عدد التقييمات والقيم التي يتم عرضها. بالنسبة إلى إصدار JSON الأولي من هذه البيانات، عليك تضمين عنوان URL التالي في طلب البحث:

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

هنا، يبرز إصدار HTML من التقرير التقييمات التي تعرض أخطاء غير محددة وقيمة فارغة:

أوجه الاختلاف بين محاكي Cloud Firestore ومحاكي الإنتاج

يسعى محاكي Cloud Firestore إلى تكرار سلوك خدمة الإنتاج على نحو دقيق مع بعض القيود الملحوظة.

دعم قواعد بيانات متعددة لـ Cloud Firestore

في الوقت الحالي، توفر واجهة مستخدم Emulator Suite ميزات الإنشاء التفاعلي والتعديل والحذف ومراقبة الطلبات والتصور الأمني لقاعدة البيانات التلقائية، ولكنها لا تتيح قواعد البيانات المسماة الإضافية.

في المقابل، ينشئ المحاكي نفسه قاعدة بيانات مُسمّاة استنادًا إلى الإعدادات في ملف firebase.json، وبشكل ضمني استجابةً لطلبات SDK أو REST API.

المعاملات

لا ينفِّذ المحاكي حاليًا جميع سلوك المعاملات الظاهر في الإنتاج. عند اختبار ميزات تتضمّن عمليات كتابة متزامنة متعددة إلى مستند واحد، قد يكون المحاكي بطيئًا في إكمال طلبات الكتابة. في بعض الحالات، قد يستغرق فتح الأقفال مدة تصل إلى 30 ثانية. ننصحك بتعديل مهلات الاختبار وفقًا لذلك، إذا لزم الأمر.

الفهارس

لا يتتبّع المحاكي الفهارس المركّبة وسينفذ بدلاً من ذلك أي استعلام صالح. احرص على اختبار تطبيقك مقابل نسخة افتراضية من Cloud Firestore لتحديد الفهارس التي ستحتاج إليها.

الحدود القصوى المسموح بها

لا يفرض المحاكي جميع الحدود المفروضة في مرحلة الإنتاج. على سبيل المثال، قد يسمح المحاكي بالمعاملات التي قد ترفضها خدمة الإنتاج باعتبارها كبيرة جدًا. تأكّد من أنّك على عِلم بالحدود الموثَّقة وعلى تصميم تطبيقك لتجنُّبها بشكلٍ استباقي.

ما الخطوات التالية؟

  • للحصول على مجموعة منظَّمة من الفيديوهات وأمثلة تفصيلية لطريقة التنفيذ، يمكنك متابعة قائمة تشغيل التدريب على محاكي Firebase.
  • تحقَّق من حالات الاستخدام المتقدّمة التي تتضمّن اختبار "قواعد الأمان" وحزمة تطوير البرامج (SDK) التجريبية لمنصة Firebase: اختبار قواعد الأمان (Firestore).
  • ونظرًا لأنّ الدوال التي تم تشغيلها هي عملية دمج نموذجية مع Cloud Firestore، يمكنك الاطّلاع على مزيد من المعلومات عن محاكي دوال Cloud لمنصة Firebase من خلال الانتقال إلى تشغيل الدوال محليًا.