שימוש בתוסף Firestore Bundle Builder

התוסף Firestore Bundle Builder‏ (firestore-bundle-builder) פורס פונקציית HTTP שמציגה חבילות נתונים של Cloud Firestore. את החבילות מגדירים במסמכי Firestore, והתוסף מגיש חבילת נתונים של קובץ בינארי סטטי באמצעות בקשות HTTP, לצד מנגנוני שמירה במטמון שונים שמוטמעים באמצעות אירוח ב-Firebase CDN או Cloud Storage. אם לא קיים חבילת תכונות או שהתוקף של חבילות קיימות פג, הפונקציה הזו תיצור חבילת תכונות חדשה ותשמור אותה במטמון לפי דרישה.

כדי להשתמש בתוסף הזה, קודם צריך ליצור מפרט אחד או יותר של חבילות ב-Firestore באמצעות לוח הבקרה לאדמינים של התוסף. מפרט החבילה הוא הדרך שבה מגדירים שאילתות עם שמות (שאילתות אוסף ונתיבים ספציפיים של מסמכים להוספה לחבילה).

במפרט החבילה אפשר גם להגדיר פרמטרים שמיועדים לשימוש בשאילתות עם שם. מגדירים ערכים לפרמטרים האלה באמצעות פרמטרים של שאילתת כתובת URL כשמפעילים את פונקציית ה-HTTP.

בקישור שלמעלה מפורטות הוראות להפעלת כלי הניהול באופן מקומי. אחרי שמגדירים את אפליקציית האינטרנט, עוברים אל localhost:3000 כדי ליצור מפרט באמצעות ממשק המשתמש:

יצירה והצגה של החבילה

אחרי שמתקינים את התוסף ויוצרים מפרט של חבילת מודעות, אפשר להתחיל ליצור ולהציג חבילות מודעות על ידי קריאה לנקודת הקצה של ה-HTTP שסופקה על ידי התוסף.

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

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

Client Integration

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

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

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

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