استخدام إضافة 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 لإنشاء الحزمة عند الطلب.

يمكنك الاستفادة من إمكانات Firebase Hosting CDN من خلال إعداد موقع استضافة 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". في هذه الحالة، يمكنك استدعاء دالة 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 (انظر أدناه).