מסמך עזר של Firebase CLI

‫Firebase CLI ‏(GitHub) מספק מגוון כלים לניהול, לצפייה ולפריסה בפרויקטים של Firebase.

לפני שמשתמשים ב-CLI של Firebase, צריך להגדיר פרויקט Firebase.

הגדרה או עדכון של ה-CLI

התקנת Firebase CLI

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

‫Windows ‫macOS ‫Linux

‫Windows

אפשר להתקין את Firebase CLI ל-Windows באחת מהדרכים הבאות:

‫macOS או Linux

אפשר להתקין את Firebase CLI ב-macOS או ב-Linux באמצעות אחת מהאפשרויות הבאות:

התחברות ובדיקה של ה-CLI של Firebase

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

1. מתחברים ל-Firebase באמצעות חשבון Google על ידי הפעלת הפקודה הבאה:

   firebase login

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

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

   firebase projects:list

   הרשימה שמוצגת צריכה להיות זהה לרשימת הפרויקטים ב-Firebase שמופיעה במסוף Firebase.

עדכון לגרסה האחרונה של CLI

בדרך כלל, מומלץ להשתמש בגרסה העדכנית ביותר של Firebase CLI.

הדרך לעדכן את גרסת ה-CLI תלויה במערכת ההפעלה ובאופן ההתקנה של ה-CLI.

הסרת Firebase CLI

הדרך להסרת ה-CLI תלויה במערכת ההפעלה ובאופן ההתקנה של ה-CLI.

שימוש ב-CLI עם מערכות CI

מומלץ לבצע אימות באמצעות Application Default Credentials כשמשתמשים ב-CLI עם מערכות CI.

(מומלץ) שימוש ב-Application Default Credentials

‫Firebase CLI יזהה וישתמש ב-Application Default Credentials אם הם מוגדרים. הדרך הכי פשוטה לאמת את ה-CLI ב-CI ובסביבות אחרות ללא ממשק משתמש היא להגדיר את פרטי הכניסה ב-Application Default Credentials.

(גרסה קודמת) אפשר להשתמש ב-FIREBASE_TOKEN

לחלופין, אפשר לבצע אימות באמצעות FIREBASE_TOKEN. השיטה הזו פחות מאובטחת מ-Application Default Credentials, ולא מומלצת יותר.

1. במכונה עם דפדפן, מתקינים את Firebase CLI.

2. כדי להתחיל את תהליך הכניסה, מריצים את הפקודה הבאה:

   firebase login:ci

3. עוברים לכתובת ה-URL שסופקה ונכנסים באמצעות חשבון Google.

4. מדפיסים טוקן רענון חדש. הסשן הנוכחי של ה-CLI לא יושפע.

5. מאחסנים את אסימון הפלט בצורה מאובטחת אבל נגישה במערכת ה-CI.

6. משתמשים באסימון הזה כשמריצים פקודות firebase. אפשר להשתמש באחת משתי האפשרויות הבאות:

   • אפשרות 1: אחסון הטוקן כמשתנה הסביבה FIREBASE_TOKEN. המערכת תשתמש בטוקן באופן אוטומטי.

   • אפשרות 2: מריצים את כל הפקודות של firebase עם הדגל --token TOKEN במערכת ה-CI.
     זהו סדר העדיפות לטעינת טוקנים: דגל, משתנה סביבתי, פרויקט Firebase רצוי.

הפעלת פרויקט Firebase

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

כדי לאתחל פרויקט חדש ב-Firebase, מריצים את הפקודה הבאה מתוך ספריית האפליקציה:

firebase init

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

• בוחרים פרויקט ברירת מחדל ב-Firebase.

  בשלב הזה משייכים את ספריית הפרויקט הנוכחית לפרויקט Firebase, כדי שפקודות ספציפיות לפרויקט (כמו firebase deploy) יפעלו מול פרויקט Firebase המתאים.

  אפשר גם לשייך כמה פרויקטים ב-Firebase (למשל פרויקט Staging ופרויקט Production) לאותה תיקיית פרויקט.

• בוחרים את מוצרי Firebase שרוצים להגדיר בפרויקט Firebase.

  בשלב הזה תתבקשו להגדיר קובצי הגדרות ספציפיים למוצרים או לתכונות שנבחרו. לפרטים נוספים על ההגדרות האלה, אפשר לעיין במסמכי העזרה של המוצר הספציפי (לדוגמה, Hosting או Authentication). שימו לב שתמיד אפשר להריץ את הפקודה firebase init מאוחר יותר כדי להגדיר מוצרים נוספים של Firebase.

בסיום האתחול, Firebase יוצר באופן אוטומטי את שני הקבצים הבאים בתיקיית השורש של האפליקציה המקומית:

• קובץ תצורה firebase.json שבו מפורטות הגדרות הפרויקט.

• קובץ .firebaserc שבו מאוחסנים כינויים של הפרויקט.

הקובץ firebase.json

הפקודה firebase init יוצרת קובץ הגדרות firebase.json בספריית השורש של הפרויקט.

קובץ firebase.json נדרש כדי לפרוס נכסים באמצעות Firebase CLI, כי הוא מציין אילו קבצים והגדרות מספריית הפרויקט נפרסים בפרויקט Firebase (כמו הגדרות Hosting, הגדרות ספק Authentication, כללי אבטחה והגדרות Cloud Functions). חלק מההגדרות יכולות להיות מוגדרות בספריית הפרויקט או במסוף Firebase, לכן חשוב לפתור בעיות פוטנציאליות בפריסה.

אפשר להגדיר את רוב האפשרויות של Firebase Hosting ישירות בקובץ firebase.json. עם זאת, עבור שירותי Firebase אחרים שאפשר לפרוס באמצעות ה-CLI של Firebase, הפקודה firebase init יוצרת קבצים ספציפיים שבהם אפשר להגדיר את ההגדרות של השירותים האלה, כמו קובץ index.js עבור Cloud Functions. אפשר גם להגדיר ווים (hooks) לפני או אחרי הפריסה בקובץ firebase.json.

קובץ firebase.json הבא הוא דוגמה מקיפה שמציגה אפשרויות הגדרה לשירותים רבים של Firebase. הוא גם מדגים תכונות כמו Cloud Functions עם כמה בסיסי קוד, הגדרה של Local Emulator Suite ותבנית Remote Config. שימו לב שקובץ firebase.json של פרויקט מסוים יכיל רק הגדרות של שירותי Firebase שהוגדרו עבור הפרויקט הספציפי הזה (לדוגמה, רק Firebase Hosting ו-Cloud Functions). הוספת המפתח $schema מאפשרת אימות והשלמה אוטומטית בהרבה עורכי קוד.

    {
      "$schema": "https://raw.githubusercontent.com/firebase/firebase-tools/master/schema/firebase-config.json",
      "hosting": {
        "public": "public",
        "ignore": [
          "firebase.json",
          "**/.*",
          "**/node_modules/**"
        ],
        "cleanUrls": true,
        "trailingSlash": false
      },
      "apphosting": {
        "backendId": "my-app",
        "rootDir": "backend",
        "ignore": [
          "firebase.json",
          "**/.*",
          "**/node_modules/**"
        ]
      },
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json"
      },
      "storage": {
        "rules": "storage.rules"
      },
      "database": {
        "rules": "database.rules.json"
      },
      "dataconnect": {
        "source": "dataconnect",
        "location": "us-central1"
      },
      "functions": [
        {
          "source": "functions",
          "codebase": "default",
          "ignore": [
            "**/.*",
            "**/node_modules/**"
          ],
          "predeploy": [
            "npm --prefix \"$RESOURCE_DIR\" run lint",
            "npm --prefix \"$RESOURCE_DIR\" run build"
          ]
        }
      ],
      "emulators": {
        "auth": {
          "port": 9099
        },
        "functions": {
          "port": 5001
        },
        "firestore": {
          "port": 8080
        },
        "hosting": {
          "port": 5000
        },
        "storage": {
          "port": 9199
        },
        "ui": {
          "enabled": true,
          "port": 4000
        },
        "singleProjectMode": true
      },
      "extensions": {
        "my-storage-resizer": "firebase/storage-resize-images@^0.1.0"
      },
      "auth": {
        "providers": {
          "anonymous": true,
          "emailPassword": true,
          "googleSignIn": {
            "oAuthBrandDisplayName": "My App",
            "supportEmail": "support@myapp.com"
          }
        }
      },
      "remoteconfig": {
        "template": "remoteconfig.template.json"
      }
    }

אמנם firebase.json משמש כברירת מחדל, אבל אפשר להעביר את הדגל --config PATH כדי לציין קובץ תצורה חלופי.

הגדרה של כמה מסדי נתונים של Cloud Firestore

כשמריצים את הפקודה firebase init, קובץ firebase.json יכיל מפתח firestore יחיד שמתאים למסד הנתונים שמוגדר כברירת מחדל בפרויקט, כמו שמוצג בדוגמה הקודמת.

אם הפרויקט מכיל כמה מסדי נתונים של Cloud Firestore, צריך לערוך את קובץ firebase.json כדי לשייך קובצי מקור שונים של אינדקסים של Cloud Firestore Security Rules ומסדי נתונים לכל מסד נתונים. משנים את הקובץ באמצעות מערך JSON, עם רשומה אחת לכל מסד נתונים.

      "firestore": [
        {
          "database": "(default)",
          "rules": "firestore.default.rules",
          "indexes": "firestore.default.indexes.json"
        },
        {
          "database": "ecommerce",
          "rules": "firestore.ecommerce.rules",
          "indexes": "firestore.ecommerce.indexes.json"
        }
      ],

Cloud Functions קבצים להתעלמות במהלך הפריסה

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

רשימת הקבצים שמתעלמים מהם כברירת מחדל, שמוצגת בפורמט JSON, היא:

"ignore": [
  ".git",
  ".runtimeconfig.json",
  "firebase-debug.log",
  "firebase-debug.*.log",
  "node_modules"
]

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

ניהול כינויים של פרויקטים

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

הוספת כינוי לפרויקט

כשבוחרים פרויקט Firebase במהלך הפעלת הפרויקט, הפרויקט מקבל באופן אוטומטי את הכינוי default. עם זאת, כדי לאפשר הפעלה של פקודות ספציפיות לפרויקט בפרויקט Firebase אחר, אבל עדיין להשתמש בספריית הפרויקט הזהה, מריצים את הפקודה הבאה מתוך ספריית הפרויקט:

firebase use --add

הפקודה הזו תבקש מכם לבחור פרויקט אחר ב-Firebase ולהקצות את הפרויקט ככינוי. הקצאות של כינויים נכתבות לקובץ .firebaserc בתוך ספריית הפרויקט.

שימוש בכינויים של פרויקטים

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

כדי לשנות את הפרויקט הפעיל, אפשר להעביר את הדגל --project עם כל פקודה ב-CLI. לדוגמה: אתם יכולים להגדיר את ה-CLI כך שיפעל מול פרויקט Firebase שהקציתם לו את הכינוי staging. אם רוצים להריץ פקודה אחת על פרויקט Firebase שהקציתם לו את הכינוי prod, אפשר להריץ למשל את הפקודה firebase deploy --project=prod.

בקרת מקורות וכינויי פרויקטים

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

אם יש לכם פרויקט פיתוח לשימושכם בלבד, אתם יכולים להעביר את הדגל --project עם כל פקודה או להריץ את הפקודה firebase use PROJECT_ID בלי להקצות כינוי לפרויקט Firebase.

הצגה ובדיקה של פרויקט Firebase באופן מקומי

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

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

• צפייה בתוכן הסטטי של האפליקציה שמתארחת ב-Firebase.
• אתם משתמשים ב-Cloud Functions כדי ליצור תוכן דינמי עבור Firebase Hosting ואתם רוצים להשתמש בפונקציות HTTP בסביבת הייצור (פריסה) כדי לבצע אמולציה של Hosting בכתובת URL מקומית.

firebase serve --only hosting

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

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

• כדי לבצע אמולציה של פונקציות HTTP ואירוח לצורך בדיקה בכתובות URL מקומיות, משתמשים באחת מהפקודות הבאות:

  firebase serve

  firebase serve --only functions,hosting // uses a flag

• כדי לבצע אמולציה רק לפונקציות HTTP, משתמשים בפקודה הבאה:

  firebase serve --only functions

בדיקה ממכשירים מקומיים אחרים

כברירת מחדל, firebase serve מגיב רק לבקשות מ-localhost. המשמעות היא שתוכלו לגשת לתוכן המתארח בדפדפן האינטרנט במחשב, אבל לא ממכשירים אחרים ברשת. אם רוצים לבצע בדיקה ממכשירים מקומיים אחרים, משתמשים בדגל --host, כך:

firebase serve --host 0.0.0.0  // accepts requests to any host

פריסה לפרויקט Firebase

‫Firebase CLI מנהל את הפריסה של קוד ונכסים בפרויקט Firebase, כולל:

• פריטים חדשים באתרים שלך Firebase Hosting
• חדש, מעודכן או קיים Cloud Functions for Firebase
• סכימות ומחברים חדשים או מעודכנים ל-Firebase SQL Connect
• Security Rules של Firebase Realtime Database
• Security Rules של Cloud Storage for Firebase
• Security Rules של Cloud Firestore
• אינדקסים של Cloud Firestore
• ההגדרה של Authentication

כדי לפרוס לפרויקט Firebase, מריצים את הפקודה הבאה מספריית הפרויקט:

firebase deploy

אפשר להוסיף הערה לכל פריסה. התגובה הזו תוצג עם פרטי הפריסה האחרים בFirebase Hosting הדף של הפרויקט. לדוגמה:

firebase deploy -m "Deploying the best new feature ever."

כשמשתמשים בפקודה firebase deploy, חשוב לשים לב לדברים הבאים:

• כדי לפרוס משאבים מתיקיית פרויקט, חייב להיות בתיקיית הפרויקט קובץ firebase.json. הקובץ הזה נוצר אוטומטית על ידי הפקודה firebase init.

• כברירת מחדל, firebase deploy יוצר גרסת הפצה לכל המשאבים שניתן לפרוס בספריית הפרויקט. כדי לפרוס תכונות או שירותים ספציפיים של Firebase, צריך להשתמש בפריסה חלקית.

פריסת שירותים ספציפיים של Firebase

אם רוצים לפרוס רק תכונות או שירותים ספציפיים של Firebase, אפשר להשתמש ברשימה מופרדת בפסיקים בדגל בפקודה firebase deploy. לדוגמה, הפקודה הבאה פורסת את התוכן Firebase Hosting ואת Cloud Storage Security Rules.

firebase deploy --only hosting,storage

בטבלה הבאה מפורטים השירותים והתכונות שזמינים לפריסה חלקית. השמות בדגלים תואמים למפתחות בקובץ ההגדרות firebase.json.

התנגשויות בהטמעה של Security Rules

במקרה של Firebase Realtime Database,‏ Cloud Storage for Firebase ו-Cloud Firestore, אפשר להגדיר את Security Rules בספריית הפרויקט המקומית או במסוף Firebase.

אפשרות נוספת למניעת התנגשויות בהטמעה היא שימוש בהטמעה חלקית והגדרה של Security Rules רק במסוף Firebase.

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

אפשר לחבר סקריפטים של Shell לפקודה firebase deploy כדי לבצע משימות לפני או אחרי הפריסה. לדוגמה, סקריפט לפני פריסה יכול לבצע טרנספילציה של קוד TypeScript לקוד JavaScript, ו-hook אחרי פריסה יכול להודיע לאדמינים על פריסות של תוכן האתר החדש אל Firebase Hosting.

כדי להגדיר פעולות Hook לפני או אחרי פריסה, מוסיפים סקריפטים של Bash לקובץ ההגדרות firebase.json. אפשר להגדיר סקריפטים קצרים ישירות בקובץ firebase.json, או להפנות לקבצים אחרים שנמצאים בספריית הפרויקט.

לדוגמה, הסקריפט הבא הוא הביטוי firebase.json למשימה מסוג postdeploy ששולחת הודעה ב-Slack אחרי פריסה מוצלחת אל Firebase Hosting.

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

קובץ הסקריפט messageSlack.sh נמצא בספריית הפרויקט ונראה כך:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://SLACK_WEBHOOK_URL

אפשר להגדיר ווים (hooks) של predeploy ו-postdeploy לכל אחד מהנכסים שאפשר לפרוס. הערה: הפעלת firebase deploy מפעילה את כל המשימות של לפני הפריסה ואחרי הפריסה שמוגדרות בקובץ firebase.json. כדי להריץ רק את המשימות שמשויכות לשירות ספציפי של Firebase, משתמשים בפקודות פריסה חלקיות.

הטיזרים predeploy ו-postdeploy מדפיסים את הפלט הרגיל ואת זרמי השגיאות של הסקריפטים בטרמינל. במקרים של כשלים, חשוב לשים לב לנקודות הבאות:

• אם פעולת ה-hook לפני הפריסה לא מסתיימת כמצופה, הפריסה מבוטלת.
• אם הפריסה נכשלת מסיבה כלשהי, לא מופעלים ווים של postdeploy.

משתני סביבה

בסקריפטים שפועלים ב-hooks של predeploy ו-postdeploy, משתני הסביבה הבאים זמינים:

• ‫$GCLOUD_PROJECT: מזהה הפרויקט הפעיל
• ‫$PROJECT_DIR: תיקיית השורש שמכילה את הקובץ firebase.json
• ‫$RESOURCE_DIR: (לסקריפטים של hosting ו-functions בלבד) המיקום של הספרייה שמכילה את משאבי Hosting או Cloud Functions שרוצים לפרוס

מכסות פריסה

יכול להיות (אבל לא סביר) שתחרגו ממכסה שמגבילה את הקצב או את הנפח של פעולות הפריסה שלכם ב-Firebase. לדוגמה, כשמפעילים מספרים גדולים מאוד של פונקציות, יכול להיות שתופיע הודעת שגיאה HTTP 429 Quota. כדי לפתור בעיות כאלה, אפשר לנסות פריסה חלקית.

החזרה למצב קודם של פריסה

אפשר לבטל Firebase Hostingפריסה מדף Firebase Hosting הפרויקט על ידי בחירת הפעולה ביטול לגרסה שנבחרה.

אי אפשר לחזור לגרסאות קודמות של Security Rules ב-Firebase Realtime Database,‏ Cloud Storage for Firebase או Cloud Firestore.

הפניות לפקודות

פקודות אדמיניסטרטיביות ב-CLI

פקודות לניהול פרויקטים

פריסה ופיתוח מקומי

הפקודות האלה מאפשרות לכם לפרוס את האתר Firebase Hosting ולקיים איתו אינטראקציה.

פקודות App Distribution

פקודות App Hosting

פקודות Authentication (ניהול משתמשים)

פקודות Cloud Firestore

פקודות Cloud Functions for Firebase

מידע נוסף מופיע במאמרי העזרה בנושא הגדרת הסביבה.

פקודות Crashlytics

פקודות SQL Connect

הפקודות האלה ותרחישי השימוש שלהן מוסברים בפירוט רב יותר במדריך העזר ל-CLI של SQL Connect.

פקודות Extensions

Extensions פקודות של בעלי תוכן דיגיטלי

פקודות Hosting

פקודות Realtime Database

שימו לב שאפשר ליצור את מופע Realtime Database הראשוני שמוגדר כברירת מחדל במסוף Firebase או באמצעות תהליך העבודה הכללי firebase init או התהליך הספציפי firebase init database.

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

פקודות Remote Config

הפקודות האלה והתרחישים לדוגמה לשימוש בהן מוסברים בפירוט במאמר בנושא שינוי Remote Config באופן פרוגרמטי.