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

כדי לנצל את היכולות של CDN ב-Firebase Hosting, אפשר להגדיר אתר ב-Firebase Hosting שמצביע על פונקציית ההצגה באמצעות כלל כתיבה מחדש. רשתות CDN יוצרות רפליקה של החבילה שלכם בשרתים רבים ושונים, כדי שהמשתמשים יוכלו לטעון את החבילה מהשרת הקרוב ביותר באופן אוטומטי. זוהי הגישה המועדפת.

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

שילוב עם לקוחות

לאחר מכן תוכלו לצרוך חבילת loadBundle API של Cloud Firestore SDKs. קודם צריך להוריד את החבילה ואז לספק אותה ל-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 (ראו בהמשך).