استخدام إضافة Firestore Bundle Builder

تنشر الإضافة Firestore Bundle Builder ‏ (firestore-bundle-builder) دالة HTTP تعرض حِزم بيانات Cloud Firestore. يمكنك تحديد الحِزم في مستندات Firestore، وتعرض الإضافة حزمة بيانات ملف ثنائي ثابت من خلال طلبات HTTP، بالإضافة إلى آليات تخزين مؤقت متعدّدة مضمّنة باستخدام شبكة توصيل المحتوى (CDN) في استضافة Firebase أو Cloud Storage. إذا لم تكن هناك حزمة أو انتهت صلاحية الحِزم الحالية، ستنشئ هذه الدالة حزمة جديدة وتخزّنها مؤقتًا عند الطلب.

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

ضمن مواصفة الحزمة، يمكنك أيضًا تحديد مَعلمات يُفترض استخدامها في طلبات البحث المُسمّاة. يمكنك ضبط قيم هذه المَعلمات باستخدام مَعلمات طلب البحث في عنوان URL عند استدعاء دالة HTTP.

يوفّر الرابط أعلاه بعض التعليمات لتشغيل أدوات المشرف محليًا. بعد إعداد تطبيق الويب، انتقِل إلى localhost:3000 لإنشاء مواصفة باستخدام واجهة المستخدم:

إنشاء الحزمة وعرضها

بعد تثبيت الإضافة وإنشاء مواصفة حزمة، يمكنك البدء في إنشاء الحِزم وعرضها من خلال استدعاء نقطة نهاية HTTP التي توفّرها الإضافة.

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

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

لإعداد ذلك في استضافة Firebase، أنشئ ملف firebase.json أو عدِّله باستخدام المحتوى التالي وانشر الموقع الإلكتروني:

{
  "hosting": {
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "/bundles/*",
        "function": "ext-firestore-bundle-builder-serve"
      }
    ]
  }
}

بعد النشر، يمكنك الوصول إلى حِزمك من شبكة توصيل المحتوى باستخدام عنوان URL لموقعك الإلكتروني. على سبيل المثال: https://your-site-url.com/bundles/:bundleId.

بدلاً من ذلك، يمكنك ضبط الإضافة لتخزين البيانات مؤقتًا في Cloud Storage إذا كنت لا تريد استخدام Firebase Hosting. في هذه الحالة، يمكنك استدعاء دالة 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 (راجِع أدناه).