ربط تطبيقك بمحاكي 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 بلا إنترنت، لأنّه ليس عليك الاتصال بالإنترنت لتنزيل إعدادات حزمة SDK

استخدِم تطبيقك للتحدّث إلى المحاكيات

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

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

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

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

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

يمكنك إعداد الإعدادات داخل التطبيق أو صفوف الاختبار للتفاعل مع 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

لا حاجة إلى إجراء أي إعدادات إضافية لاختبار وظائف Cloud التي يتم تشغيلها بواسطة أحداث 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 CLI. يمكنك تمرير معرّف مشروع إلى initializeApp مباشرةً أو ضبط المتغيّر البيئي GCLOUD_PROJECT.

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

export GCLOUD_PROJECT="your-project-id"

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

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

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

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

من الطبيعي أن ينتظر الرمز تأكيد REST بأنّ عملية الفلاش قد اكتملت أو تعذّرت.

يمكنك تنفيذ هذه العملية من خلال بيئة Shell:

// 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 > الطلبات للاطّلاع على ترتيب التقييم التفصيلي لكل طلب.

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

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