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

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

Client Integration

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