ניהול הגדרות של פרויקט באמצעות המניפסט של התוספים

מניפסט של תוספים הוא רשימה של מופעי תוספים וההגדרות שלהם. באמצעות המניפסט, אתם יכולים:

  • שיתוף הגדרות התוספים עם אחרים
  • להעתיק את הגדרות התוספים בין פרויקטים שונים (למשל, מפרויקט ה-staging לפרויקט הייצור)
  • פריסת כל התוספים בבת אחת
  • כדי לבדוק איך התוספים פועלים עם האפליקציה, אפשר להשתמש בFirebase Local Emulator Suite
  • העברת הגדרת התוספים לבקרת המקור
  • הכללת תוספים בצינור עיבוד הנתונים של CI/CD

מניפסט של תוספים מורכב משני חלקים:

  • הקטע extensions ב-firebase.json, שהוא מיפוי של מזהה המופע להפניה לגרסת התוסף. לדוגמה:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • קובצי .env שמכילים את ההגדרות של כל אחד מהמופעים של התוספים, בספריית המשנה extensions/ של ספריית הפרויקט ב-Firebase. לדוגמה, למכונה של storage-resize-images יכול להיות קובץ .env כמו זה:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.firebasestorage.app
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

יצירת מניפסט של תוספים

יש שלוש דרכים ליצור מניפסט של תוספים:

  • ניהול מניפסט התוספים באמצעות Firebase CLI
  • ייצוא הגדרות התוספים של פרויקט
  • עריכה ידנית של קובצי המניפסט

שתי השיטות הראשונות מוסברות בהמשך.

ניהול המניפסט של התוספים באמצעות Firebase CLI

אפשר להריץ את רוב הפקודות של ext: ב-Firebase CLI עם האפשרות --local כדי לעדכן את מניפסט התוספים בלי לשנות את ההגדרות הנוכחיות של הפרויקט.

לדוגמה:

firebase ext:install --local firebase/firestore-bigquery-export

הפעלת הפקודה שלמעלה תבקש מכם להגדיר את הגרסה העדכנית של התוסף firebase/firestore-bigquery-export ולשמור את ההגדרות במניפסט, אבל היא לא תפרוס את ההגדרות בפרויקט.

הנה עוד כמה דוגמאות לפקודות שמשנות את המניפסט של התוספים:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

ייצוא הגדרות התוספים של הפרויקט

כדי לשמור במניפסט את הגדרות התוספים הנוכחיות של הפרויקט:

  1. אם עדיין לא עשיתם זאת, הגדירו את Firebase CLI.
  2. בשורת הפקודה, עוברים לספריית הפרויקט. (ספריית הפרויקט מכילה את הקובץ firebase.json).
  3. מריצים את הפקודה ext:export: 
    firebase ext:export

הפקודה ext:export תוסיף קטע extensions לקובץ firebase.json. בנוסף, הפקודה ext:export יוצרת ספריית extensions שמכילה קובץ .env לכל מופע של תוסף שהתקנתם. הקבצים האלה מכילים את פרמטרי ההגדרות של כל מכונה.

בודקים את הגדרת התוספים באמצעות Firebase Local Emulator Suite

אחרי שמוסיפים כמה מופעים של תוספים למניפסט התוספים, אפשר לבדוק אותם באמצעות Local Emulator Suite.

  1. מתקינים ומגדירים את Local Emulator Suite.

  2. מפעילים את Local Emulator Suite:

    • כדי להפעיל את חבילת הכלים לאמולטור באופן אינטראקטיבי, מריצים את הפקודה: firebase emulators:start
    • כדי להפעיל את כלים לאמולטור ולהריץ סקריפט בדיקה, מריצים את הפקודה: firebase emulators:exec my-test.sh

עכשיו, אם יש מופעים של תוספים שרשומים במניפסט, Local Emulator Suite יוריד את קוד המקור של התוספים האלה אל ~/.cache/firebase/extensions. אחרי ההורדה, Local Emulator Suite יתחיל לפעול ותוכלו להפעיל כל אחת מהפונקציות של התוספים שמופעלות ברקע, ולחבר את האפליקציה ל-Emulator Suite כדי לבדוק את השילוב שלהם עם האפליקציה.

פריסת הגדרת תוספים בפרויקט

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

כדי לפרוס מניפסט של תוספים:

  1. בשורת הפקודה, עוברים לספרייה שמכילה את הגדרות התוספים השמורות. (זו הספרייה שמכילה את firebase.json. אם הרצתם את ext:export, אתם כבר בספרייה הנכונה.
  2. מריצים את הפקודה deploy. אם רוצים לפרוס את התוספים בפרויקט אחר, צריך לציין גם את --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

הפקודה deploy תאמת את ההגדרות של כל מופע, תציג שאלה אם אתם רוצים למחוק מופעי תוספים מפרויקט היעד שלא מופיעים ברשימה ב-firebase.json, ואז תפרוס את כל מופעי התוספים.

הגדרות של תוספים ספציפיים לפרויקט

אפשר להשתמש בהגדרות השמורות של התוספים כדי לפרוס אותם בכמה פרויקטים שונים, למשל פרויקט בסביבת Staging ופרויקט בסביבת ייצור. במקרה כזה, יכול להיות שערכי הפרמטרים יהיו שונים בכל פרויקט. קבצי .env ספציפיים לפרויקט מאפשרים את זה:

  • מזינים ערכי פרמטרים שונים בין פרויקטים ב-extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID
  • מזינים ערכי פרמטרים משותפים ב-extensions/EXTENSION_INSTANCE_ID.env.

לפעמים, יכול להיות שתרצו להשתמש בערך פרמטר אחר כשאתם מדמים את התוספים: לדוגמה, יכול להיות שתרצו לספק מפתח API לבדיקה במקום מפתח API לסביבת הייצור. מזינים את הפרמטרים האלה בקובץ .local:

  • מוסיפים פרמטרים לא סודיים שרוצים להשתמש בהם במהלך האמולציה בקובץ extensions/EXTENSION_INSTANCE_ID.env.local
  • הזנת ערכי פרמטרים סודיים ב-extensions/EXTENSION_INSTANCE_ID.secret.local