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

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

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

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

لاختيار المشروع الذي تريد استخدامه، شغِّل الأمر firebase use في واجهة سطر الأوامر (CLI) ضمن دليل العمل قبل بدء المحاكيات. يمكنك أيضًا تمرير العلامة --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، عدِّل عنوان URL إلى localhost:4000/firestore/ecommerce/data.

بدء المحاكي في إصدار معيّن

سيبدأ المحاكي في الإصدار المحدّد ضمن firestore.edition قسم في ملف firebase.json file. يمكنك أيضًا تحديد إصدار ضمن قسم emulators.firestore.edition في ملف firebase.json. القيم الصالحة للإصدار هي standard وenterprise. إذا حدّدت edition في كلا الإعدادَين، ستكون الأولوية لقسم emulators.firestore.edition.

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

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

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

Kotlin
// 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
}
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);
Swift
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settings

Web

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

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

Web

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

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

Admin SDK ثوانٍ

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

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

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

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

واجهة برمجة التطبيقات REST في Cloud Firestore

يوفّر محاكي Cloud Firestore نقطة نهاية REST للتفاعل مع قاعدة البيانات. يجب إجراء جميع طلبات واجهة برمجة التطبيقات REST إلى نقطة النهاية http://localhost:8080/v1.

يتّبع المسار الكامل لطلب REST النمط التالي:

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

على سبيل المثال، لسرد جميع المستندات في مجموعة users للمشروع my-project-id، يمكنك استخدام curl:

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

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

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

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

الحدود

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

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