ربط تطبيقك بمحاكي 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)

إعداد تطبيقك للتواصل مع المحاكيات

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

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

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

يوفّر محاكي Cloud Firestore نقطة نهاية REST للتفاعل مع قاعدة البيانات. يجب إجراء جميع طلبات REST API إلى نقطة النهاية 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 API.

المعاملات

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

المؤشرات

لا يتتبّع المحاكي المؤشرات المركّبة، بل سيشغّل أي طلب بحث صالح. احرص على اختبار تطبيقك على مثيل حقيقي من Cloud Firestore لتحديد المؤشرات التي ستحتاج إليها.

الحدود

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

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