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

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:

   • כדי להפעיל את חבילת האמולטור באופן אינטראקטיבי, מריצים את: firebase emulators:start
   • כדי להריץ את חבילת האמולטור ולהריץ סקריפט בדיקה, מריצים את: 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 לבדיקה במקום מפתח בסביבת ייצור. מוסיפים את הפרמטרים הבאים לקובץ .local:

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