שימוש בתוסף 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 (ראו בהמשך).