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

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
    • כדי להריץ את 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