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

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

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

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

بدء تشغيل المحاكي في إصدار محدّد

سيبدأ المحاكي في الإصدار المحدّد ضمن قسم firestore.edition في ملف firebase.json. يمكنك أيضًا تحديد إصدار ضمن قسم 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
Unity
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

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);
}

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

‫Admin SDK ثانية

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

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

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

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

Cloud Firestore REST API

يوفّر محاكي 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 حقيقي لتحديد الفهارس التي ستحتاج إليها.

الحدود

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

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

  • للاطّلاع على مجموعة منظَّمة من الفيديوهات وأمثلة تفصيلية حول طريقة التنفيذ، يمكنك متابعة قائمة تشغيل التدريب على محاكيات Firebase.
  • يمكنك الاطّلاع على حالات الاستخدام المتقدّمة التي تتضمّن اختبار "قواعد الأمان" وحزمة تطوير البرامج (SDK) الخاصة باختبار Firebase: اختبار قواعد الأمان (Firestore).
  • بما أنّ الدوال التي يتم تشغيلها هي عملية تكامل نموذجية مع Cloud Firestore، يمكنك الاطّلاع على مزيد من المعلومات حول محاكي Cloud Functions for Firebase على تشغيل الدوال محليًا.