שימוש בתוסף 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 או מקובץ Cloud Storage. כשהתוקף של כל המטמון יפוג, בקשת הצגה חדשה תפעיל שאילתות של Firestore כדי ליצור את החבילה על פי דרישה.

כדי לנצל את היכולות של CDN ב-Firebase Hosting, אפשר להגדיר אתר ב-Firebase Hosting שמצביע על פונקציית ההצגה באמצעות כלל כתיבה מחדש. רשתות 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.

לחלופין, אם אתם לא רוצים להשתמש באירוח ב-Firebase, אתם יכולים להגדיר את התוסף לשמירת נתונים במטמון ב-Cloud Storage. במקרה כזה, צריך לקרוא ישירות לפונקציית ה-HTTP שנפרסה כדי ליצור חבילות.

שילוב לקוח

לאחר מכן תוכלו לצרוך את החבילה באמצעות ה-API 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);

אם ציינת שאילתות, אפשר להשתמש ב-API ‏namedQuery כדי להריץ שאילתה מהחבילה:

import { getFirestore, namedQuery } from "firebase/firestore";
const query = await namedQuery(getFirestore(), "queryId");
const snapshot = await getDocsFromCache(query);

מזהי השאילתות מוגדרים כמפתח של כל הגדרת נכס queries (ראו בהמשך).