تعمل إضافة "أداة إنشاء حِزم Firestore" (firestore-bundle-builder) على نشر دالة HTTP تعرِض حِزم بيانات Cloud Firestore. يمكنك تحديد الحِزم في مستندات Firestore، وتعرض الإضافة حِزمة بيانات الملفات الثنائية الثابتة من خلال طلبات HTTP، بالإضافة إلى آليات مختلفة مضمّنة لتخزين البيانات المؤقت باستخدام CDN أو Cloud Storage في Firebase Hosting. عندما لا تتوفّر حِزمة أو انتهت صلاحية الحِزم الحالية، ستنشئ هذه الدالة حِزمة جديدة وتخزّنها مؤقتًا عند الطلب.
لاستخدام هذه الإضافة، عليك أولاً إنشاء مواصفات حِزمة واحدة أو أكثر في Firestore باستخدام لوحة بيانات المشرف في الإضافة. تشير مواصفات الحِزمة إلى كيفية تحديد طلبات البحث المُسمّاة (طلبات بحث المجموعة ومسارات مستندات محدّدة لإضافتها إلى الحِزمة).
داخل مواصفات الحِزمة، يمكنك أيضًا تحديد مَعلمات مخصّصة للاستخدام في طلبات البحث المُعنوَنة. يمكنك ضبط قيم لهذه المَعلمات باستخدام مَعلمات طلب البحث لعنوان URL عند استدعاء دالة HTTP.
يقدّم الرابط أعلاه بعض التعليمات التي تتيح لك تشغيل أدوات المشرف محليًا. بعد إعداد تطبيق الويب، انتقِل إلى localhost:3000 لإنشاء مواصفة باستخدام واجهة المستخدم:
إنشاء الحزمة وعرضها
بعد تثبيت الإضافة وإنشاء مواصفات حِزمة، يمكنك بدء إنشاء الحِزم وعرضها من خلال طلب نقطة نهاية HTTP التي تقدّمها الإضافة.
استنادًا إلى مواصفات الحِزمة، قد يتم عرض الحِزمة المطلوبة من ذاكرة التخزين المؤقت للعميل أو ذاكرة التخزين المؤقت في Firebase Hosting أو من ملف في Cloud Storage. عندما تنتهي صلاحية جميع ذاكرات التخزين المؤقت، سيؤدي طلب عرض جديد إلى تشغيل طلبات بحث Firestore لإنشاء الحِزمة عند الطلب.
يمكنك الاستفادة من إمكانات شبكة توصيل المحتوى (CDN) في "استضافة Firebase" من خلال إعداد موقع إلكتروني على "استضافة Firebase" يشير إلى دالة العرض باستخدام قاعدة إعادة كتابة. تعمل شبكات توصيل المحتوى (CDN) على نسخ حِزمك على العديد من الخوادم المختلفة، حتى يتمكّن المستخدمون من تحميل الحِزمة من أقرب خادم تلقائيًا. وهذا هو النهج المفضّل.
لإعداد هذا الإجراء في "استضافة Firebase"، أنشئ ملف firebase.json أو عدِّله يتضمّن المحتوى التالي ونشر الموقع الإلكتروني:
{
"hosting": {
"ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
"rewrites": [
{
"source": "/bundles/*",
"function": "ext-firestore-bundle-builder-serve"
}
]
}
}
بعد نشر الحِزم، يمكنك الوصول إليها من شبكة توصيل المحتوى (CDN) باستخدام عنوان URL لموقعك الإلكتروني. على سبيل المثال: https://your-site-url.com/bundles/:bundleId.
بدلاً من ذلك، يمكنك ضبط الإضافة لتخزين البيانات مؤقتًا في Cloud Storage إذا كنت لا تريد استخدام ميزة "استضافة Firebase". في هذه الحالة، يمكنك استدعاء دالة HTTP المنشورة مباشرةً لإنشاء الحِزم.
دمج العميل
بعد ذلك، يمكنك استخدام حزمة تتضمّن واجهة برمجة التطبيقات loadBundle لحِزم تطوير البرامج (SDK) لمنصّة Cloud Firestore. يجب أولاً تنزيل الحِزمة، ثم تقديمها إلى حزمة تطوير البرامج (SDK). على سبيل المثال:
import { loadBundle } from "firebase/firestore";
// Download the bundle from the Firebase Hosting CDN:
const bundle = await fetch("/bundles/:bundleId");
// If not using a CDN, download the bundle directly:
// const bundle = await fetch('https://<location>-<project-id>.cloudfunctions.net/ext-firestore-bundle-builder-serve/:bundleId');
await loadBundle(bundle);
بعد تحميل الحزمة، يمكنك استخدام البيانات من الحزمة:
إذا حدّدت صفيفًا من مسارات المستندات عند تحديد الحِزمة، يمكنك الحصول على بيانات المستند على جهاز العميل من خلال الحِزمة:
import { getFirestore, doc, getDocFromCache } from "firebase/firestore";
// Bundle Document IDs: ['users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2']
const ref = doc(getFirestore(), "users/92x1NgSWYKUC4AG4s2nHGMR2ikZ2");
const snapshot = await getDocFromCache(ref);
إذا حدّدت طلبات بحث، يمكنك استخدام واجهة برمجة التطبيقات namedQuery لتشغيل طلب بحث من الحِزمة:
import { getFirestore, namedQuery } from "firebase/firestore";
const query = await namedQuery(getFirestore(), "queryId");
const snapshot = await getDocsFromCache(query);
يتم تعريف أرقام تعريف طلبات البحث كمفتاح لكلّ تعريف لسمة queries (راجِع ما يلي).