ربط تطبيقك بمحاكي 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 الحقيقي هو المشروع الذي أنشأته وضبطته (على الأرجح من خلال وحدة تحكّم Firebase).

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

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

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

تجريبي

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

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

عند العمل مع مشاريع 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 إضافية غير قاعدة البيانات التلقائية، يُرجى الرجوع إلى دليل قواعد البيانات المتعددة.

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قيد التحميل، يعملان معًا تلقائيًا.

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.

حزمة تطوير البرامج (SDK) لمشرف Node.js
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:

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

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

الحدود

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

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