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

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

  • שיתוף הגדרות התוספים עם אחרים
  • העתקת הגדרת התוספים בין פרויקטים שונים (למשל, מפרויקט ההכנה לפרויקט הייצור)
  • פריסת כל התוספים בבת אחת
  • בודקים איך התוספים פועלים עם האפליקציה באמצעות 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

אפשר להריץ את רוב הפקודות של Firebase CLI ext: עם האפשרות --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 יתחיל לפעול ותוכלו להפעיל כל אחת מהפונקציות של התוספים שמופעלות ברקע ולחבר את האפליקציה לחבילת האמולטורים כדי לבדוק את השילוב שלהם באפליקציה.

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

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

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

  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