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

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

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

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

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

تتيح Local Emulator Suite إمكانية محاكاة مشاريع Firebase الحقيقية. لإصدار تجريبي من المشاريع.

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

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

تحتوي المشروعات الحقيقية على موارد مباشرة، مثل مثيلات قاعدة البيانات والتخزين أو المجموعات أو الدوال أو أي مورد آخر أعددته لمنصة Firebase مشروعك.

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

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

تجريبي

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

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

عند العمل مع مشاريع 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

أنظمة 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

لا حاجة إلى إجراء أي إعداد إضافي لاختبار دوال السحابة التي تم تشغيلها بواسطة أحداث 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.

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

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

لا توفّر حزمة تطوير البرامج (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 أيضًا. لمزيد من المعلومات، راجع مرجع أوامر المحاكي.

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

أثناء عملك من خلال النماذج الأوّلية وحلقات الاختبار، يمكنك استخدام أدوات التصور والتقارير المقدَّمة من "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.

المعاملات

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

المؤشرات

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

الحدود

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

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