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

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

اختيار مشروع في 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
}
EmulatorSuite.kt
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);
EmulatorSuite.java
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web

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

Web

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

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

حزم SDK للمشرف

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

إذا كان الرمز قيد التشغيل داخل محاكي Cloud Functions، يتم ضبط رقم تعريف مشروعك والإعدادات الأخرى تلقائيًا عند طلب البيانات من 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 خصيصًا لهذا الغرض، والتي يمكن استدعاؤها من خلال خطوة إعداد إطار عمل اختباري أو TearDown أو من درس اختبار أو من واجهة الأوامر (مثلاً من خلال curl) قبل بدء الاختبار. ويمكنك استخدام هذا الأسلوب كبديل لإيقاف عملية المحاكي.

نفِّذ عملية حذف HTTP بطريقة مناسبة، مع توفير رقم تعريف مشروع 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 أيضًا. لمزيد من المعلومات، يُرجى الاطّلاع على مرجع أوامر المحاكي.

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

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

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

يتيح لك محاكي 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 الحقيقي لتحديد الفهارس التي ستحتاج إليها.

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

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

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