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

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

  • שיתוף ההגדרות של התוספים עם אחרים
  • להעתיק את הגדרות התוספים בין פרויקטים שונים (למשל, מפרויקט ההרצה לפרויקט הייצור)
  • פריסת כל התוספים בבת אחת
  • בדיקת האופן שבו התוספים פועלים עם האפליקציה באמצעות 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}.appspot.com
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

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

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

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

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

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

אפשר להריץ את רוב הפקודות של ext: ב-CLI של Firebase עם האפשרות --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:

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

עכשיו, אם יש לכם מכונות של תוספים שמפורטות במניפסט, ה-Local Emulator Suite יוריד את קוד המקור של התוספים האלה אל ~/.cache/firebase/extensions. אחרי ההורדה, Local 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