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

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

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

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

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

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

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

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

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

لإعداد ذلك في "استضافة 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 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 (انظر أدناه).