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

قبل ربط تطبيقك بمحاكي Cloud Firestore، تأكَّد من أنّك تفهم سير عمل Firebase Local Emulator Suite بشكل عام، ومن أنّك تثبّت Local Emulator Suite وتضبط إعداداته وتراجع أوامر واجهة سطر الأوامر.

اختيار مشروع على Firebase

يحاكي Firebase Local Emulator Suite المنتجات لمشروع واحد على Firebase.

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

تتيح Local Emulator Suite محاكاة مشاريع Firebase الحقيقية ومشاريع العرض التوضيحي.

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

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

تجهيز تطبيقك للتواصل مع المحاكيات

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

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

للعمل مع قواعد البيانات التلقائية والمسمّاة بشكل تفاعلي في Emulator Suite UI، عدِّل عنوان URL في شريط العناوين في المتصفح لاختيار قاعدة بيانات تلقائية أو مسمّاة.

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

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

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

// 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
}
EmulatorSuite.kt

// 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);
EmulatorSuite.java

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

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

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

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

لا يلزم إجراء أي إعداد إضافي لاختبار <0x0A>Cloud Functions التي يتم تشغيلها بواسطة أحداث Firestore باستخدام المحاكي. عند تشغيل كلّ من محاكي Firestore ومحاكي Cloud Functions، سيعملان معًا تلقائيًا.

Admin SDK ثانية

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

إذا كان الرمز البرمجي يعمل داخل محاكي Cloud Functions، يتم ضبط معرّف مشروعك والإعدادات الأخرى تلقائيًا عند استدعاء initializeApp.

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

admin.initializeApp({ projectId: "your-project-id" });

export GCLOUD_PROJECT="your-project-id"

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

لا يوفّر الإصدار العلني من 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 for Firebase تصدير البيانات من مثيل محاكي قيد التشغيل. حدِّد مجموعة أساسية من البيانات لاستخدامها في اختبارات الوحدات أو سير عمل التكامل المستمر، ثم صدِّرها لمشاركتها مع الفريق.

firebase emulators:export ./dir

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

firebase emulators:start --import=./dir

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

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

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

تصوُّر نشاط "قواعد الأمان"

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

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

يتيح لك محاكي Cloud Firestore عرض طلبات العميل في Emulator Suite UI، بما في ذلك تتبُّع التقييم لـ Firebase Security Rules.

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

عرض تقارير تقييمات "القواعد"

أثناء إضافة &quot;قواعد الأمان&quot; إلى النموذج الأوّلي، يمكنك تصحيح الأخطاء فيها باستخدام Local Emulator Suite أدوات تصحيح الأخطاء.

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

للحصول على التقارير، أرسِل طلب بحث إلى نقطة نهاية مكشوفة على المحاكي أثناء تشغيله. للحصول على نسخة متوافقة مع المتصفح، استخدِم عنوان 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 UI إنشاء قواعد بيانات تلقائية وتعديلها وحذفها بشكل تفاعلي، بالإضافة إلى مراقبة الطلبات وعرض الأمان، ولكن لا تتيح إنشاء قواعد بيانات إضافية تحمل أسماء.

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

المعاملات

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

الفهارس

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

الحدود

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

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

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