מדריך לפקודות של Firebase CLI ל-Data Connect

‫Firebase CLI הוא כלי שמאפשר לכם לנהל ולהגדיר מוצרים ושירותים של Firebase משורת הפקודה.

ה-CLI מספק פקודות שאפשר להשתמש בהן כדי לבצע מגוון Data Connect משימות, כמו יצירת Data Connect פרויקט חדש, אתחול של ספריית עבודה מקומית תואמת, הגדרת Data Connect אמולטור, הצגת רשימה של Data Connect משאבים, יצירת SDK של לקוח ועוד.

פקודות הגדרה

הוספת Data Connect לפרויקט Firebase

firebase init

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

firebase init

תהליך העבודה של firebase init כולל הגדרה של שירות ומסד נתונים, ואם רוצים, גם התקנה של אמולטור Data Connect והגדרה של ערכות SDK שנוצרו.

הגדרת השירות ומסד הנתונים

אם בוחרים באפשרות dataconnect להגדרת המוצר, ממשק ה-CLI יבקש שם ומיקום חדשים לשירות, וישאל אם לקשר מופע קיים של Cloud SQL for PostgreSQL או ליצור מופע חדש.

אם מחובר מופע קיים, ה-CLI בודק אם יש הגדרות תואמות, כמו אימות IAM וכתובות IP ציבוריות.

הגדרת Local Emulator Suite

תהליך ה-CLI מציע להגדיר אמולטורים, כולל אמולטור Data Connect.

פקודות אמולטור Data Connect

הפעלת האמולטור Data Connect

emulators:start/exec

firebase emulators:start/exec

משתמשים בגרסה Local Emulator Suite של אמולטור Data Connect במצב אינטראקטיבי עם start או במצב לא אינטראקטיבי מבוסס-סקריפט עם exec.

ייצוא וייבוא של נתוני PostgreSQL מקומיים

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

הייצוא מאוחסן כתמונות מצב של מסד הנתונים המקומי של PostgreSQL.

‫Data Connect מציע שלוש גישות לייצוא או לייבוא:

  • ייצוא אוטומטי/ייבוא אוטומטי שהוגדר ב-firebase.json כדי לספק גיבויים של תמונות מצב כשמכבים ומפעילים את האמולטור
  • ייצוא או ייבוא ידניים באמצעות ה-CLI
  • ייצוא או ייבוא ידני באמצעות הממשק של התוסף VS Code

ייצוא וייבוא אוטומטיים שהוגדרו ב-firebase.json

כדי לגבות נתונים בין סשנים של פיתוח, צריך לציין מיקום לגיבוי אוטומטי במהלך רצף הפעולות firebase init. המיקום הזה נשמר בfirebase.json בשדה emulators.dataconnect.dataDir. כל שינוי בנתונים שתבצעו יישמר כאן באופן אוטומטי בין הפעלות של האמולטור, ולכן הוא שימושי במהלך בדיקות מקומיות וחיפושים.

ייצוא ידני: emulators:export וemulators:start/exec --import

בזמן שהאמולטור Data Connect פועל, מריצים את הפקודה firebase emulators:export במסוף נפרד כדי לשמור תמונת מצב של הנתונים. אחר כך תוכלו להפעיל את האמולטור מתמונת המצב הזו באמצעות הדגל --import.

‫
# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

ייצוא או ייבוא ידני: תוסף VS Code

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

אפשר לייבא את הנתונים האלה באמצעות ה-CLI, כמו שמתואר בקטע הקודם. אפשר גם לייבא את הנתונים האלה לפני שמפעילים את האמולטור דרך VS Code. לשם כך, לוחצים על הקישור Configure emulator ומגדירים את Import Path.

פקודות לניהול סכימות ומחברים

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

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

פריסת סכימות ומחברים

לפרוס

firebase deploy

הפקודה הזו פורסת משאבים לשירותי Data Connect שמופיעים באינדקס ב-firebase.json. אם צריך, מתבצעת מיגרציה של הסכימה ועדכון של המחבר.

Command תיאור

‫firebase deploy

דגל תיאור

–-only dataconnect

פריסת סכימות ומחברים לכל שירותי Data Connect בפרויקט הזה, אבל לא פריסה של משאבים אחרים של מוצרי Firebase.

‪–-only dataconnect:serviceId

פריסת סכימה ומחברים לשירות Data Connect שצוין.

‫–-only dataconnect:serviceId:connectorId

פריסת מחבר יחיד לשירות Data Connect שצוין.

‪–-only dataconnect:serviceId:schema

פריסת הסכימה לשירות Data Connect שצוין.

בעזרת הדגלים –-only, אפשר להעביר ערכים מופרדים בפסיקים כדי לפרוס כל קבוצת משנה של משאבים שרוצים.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

הצגת רשימה של שירותים, סכימות ומחברים של Data Connect

dataconnect:services:list

firebase dataconnect:services:list

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

השוואה והעברה של סכימות SQL

כשמריצים את הפקודה firebase deploy, ה-CLI מבצע השוואה של סכימת SQL לפני פריסת העדכונים. אפשר גם לבצע את ההשוואה ולעדכן ישירות באמצעות קבוצה של פקודות dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

הפקודה הזו משווה סכימה מקומית של שירות עם הסכימה הנוכחית של מסד הנתונים התואם ב-Cloud SQL. הוא מדפיס את הפקודות שיופעלו כדי להעביר את מסד הנתונים לסכימה החדשה.

Command תיאור

‫firebase dataconnect:sql:diff

דגל/פרמטר תיאור

serviceId

מציינים את השירות. אם לא מציינים שירותים, יודפס ההבדל בין כל השירותים בקובץ firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

הפקודה הזו מחילה שינויים בסכימה המקומית על מסד נתונים של Cloud SQL בשירות.

כשמגדירים פרויקט מקומי חדש של Data Connect עם קובץ dataconnect.yaml שמוגדר כברירת מחדל, הפקודה dataconnect:sql:migrate מציגה בקשה לביצוע שינויים נדרשים, ואז בקשה לביצוע שינויים אופציונליים, לפני שהיא מבצעת את השינויים. אפשר לשנות את ההתנהגות הזו כך שתמיד יכללו או יתעלמו משינויים אופציונליים. לשם כך, צריך לעדכן את ההגדרה של dataconnect.yaml, כמו שמוסבר במאמר העברת סכימה במצב מחמיר או במצב תואם.

בסביבות אינטראקטיביות, ה-CLI מציג כל הצהרת SQL להעברה (ואם היא הרסנית) ומבקש את השינויים שרוצים להחיל. העברת הדגל --force שקולה לאישור כל ההנחיות.

בסביבות לא אינטראקטיביות:

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

firebase dataconnect:sql:migrate

דגל תיאור

serviceId

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

‫‎–-force

אישור אוטומטי של הנחיות.

כמו בדגלים אחרים של --only, אפשר לציין כמה שירותים מופרדים בפסיקים.

העברת סכימה במצב קפדני או במצב תאימות

למיגרציות של סכימות יש שני מצבים שונים של אימות סכימות: strict ו-compatible.Data Connect באימות במצב קפדני, סכימת מסד הנתונים צריכה להיות זהה לסכימת האפליקציה לפני שאפשר לפרוס את סכימת האפליקציה. כדי לאמת את מצב התאימות, סכימת מסד הנתונים צריכה להיות תואמת לסכימת האפליקציה, כלומר רכיבים במסד הנתונים שלא נמצאים בשימוש בסכימת האפליקציה לא ישונו.

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

מגדירים את מצב האימות באמצעות המפתח schemaValidation בקובץ dataconnect.yaml. אם לא מציינים את schemaValidation, ה-CLI מחיל שינויים תואמים ומציג בקשה לפני ביצוע שינויים מחמירים. הסבר על ההגדרות

ניהול שינויים במחברים

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

הערכת ההשפעה תרחיש
רמת אזהרה (תואם לחיבור קווי, יכול להיות שינוי בהתנהגות)
  • הסרת שדה שאפשר להזין בו ערך null משאילתה בלי הערה @retired.
שינוי שעלול לשבור את התאימות (לא תואם לחוטים, עלול לשבור את התאימות של לקוחות)
  • שינוי משתנה שניתן להגדיר בו ערך null למשתנה שלא ניתן להגדיר בו ערך null ללא ערך ברירת מחדל.
  • שינוי סוג הנתונים של שדה כך שיהיה תואם ל-JSON (למשל Int ל-Float).
  • שינוי עמודה שאינה null לעמודה שניתן להגדיר בה null.
  • הסרת משתנה שאפשר להקצות לו ערך null ללא הערה @retired.
  • הסרת משתנה שאינו null עם ערך ברירת מחדל ללא הערת @retired.
שינוי שובר (לא תואם ל-wire, יגרום לשיבוש אצל לקוחות)
  • הסרת פעולה ללא הערה @retired.
  • הסרת שדה שאינו null משאילתה ללא הערה @retired.
  • הוספת משתנה שאינו null ללא ערך ברירת מחדל.
  • שינוי סוג הנתונים של שדה למשהו לא תואם (למשל String ל-Int).
  • הסרת משתנה שאינו null ללא ערך ברירת מחדל וללא הערה @retired.

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

בסביבות לא אינטראקטיביות:

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

בדיקת קוד ההרשאה

‫Data Connect עוזר לכם לבדוק את אסטרטגיית ההרשאות שלכם על ידי ניתוח קוד המחבר כשאתם מבצעים פריסה לשרת באמצעות firebase deploy מ-Firebase CLI. אתם יכולים להשתמש בביקורת הזו כדי לבדוק את בסיס הקוד.

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

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

אזהרות והנחיות תמיד יופיעו במקרים הבאים:

  • PUBLIC

בנוסף, אם לא מוסיפים מסננים לרמות הגישה הבאות באמצעות auth.uid, מוצגות אזהרות והנחיות:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

מידע נוסף על הרשאות זמין במדריך בנושא הרשאות ואישורים.

פקודות SDK

יצירת ערכות SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

הפקודה הזו יוצרת את ערכות ה-SDK עם ההקלדה שהוגדרו בקובץ connector.yaml.

אפשר גם לעיין במדריכים לעבודה עם ערכות ה-SDK לאינטרנט, ערכות ה-SDK ל-Android וערכות ה-SDK ל-iOS.

Command תיאור

firebase dataconnect:sdk:generate

דגל תיאור

–-watch

הכלי ממשיך לפעול ויוצר ערכות SDK חדשות בכל פעם ששומרים שינויים בקובצי הסכימה והמחבר של GQL.

אם היצירה נכשלת, השגיאות יודפסו ל-stdout, הקוד שנוצר לא ישתנה והפקודה תמשיך לפעול.

‫–-only connectorId:platform

אפשר ליצור ערכות SDK רק לפלטפורמה אחת ולמחבר אחד.

אפשר להעביר ערכים מופרדים בפסיקים באמצעות הדגלים –only.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

פקודות ניהול של Cloud SQL

הקצאת תפקידי SQL ל-Cloud SQL

‫Data Connect פועל על גבי מכונת PostgreSQL משלכם שמארחת ב-Cloud SQL. פקודות של תפקידי SQL עוזרות לכם לנהל הרשאות בטבלאות של מסד הנתונים.

dataconnect:sql:setup

firebase dataconnect:sql:setup

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

זרימת ההקצאה והניהול של מסד הנתונים שמוגדרת כברירת מחדל מניחה שהפרויקט שלכם משתמש במסד נתונים חדש (greenfield), וכשמפעילים את firebase deploy, המערכת מציגה את השינויים בסכימת מסד הנתונים שצריך לבצע ומבצעת את ההעברות אחרי שמאשרים.Data Connect אם זה התהליך המועדף עליכם, dataconnect:sql:setup יבקש מכם להעניק הרשאות, כולל בעלות על סכימות superuser.

במסדי נתונים קיימים (brownfield), יכול להיות שיש לכם תהליך עבודה משלכם להעברת סכימות, ואתם רוצים לשמור על הבעלות על הסכימה בעצמכם. אם זה התהליך המועדף עליכם, הקפידו לסרב להצעה של dataconnect:sql:setup לטפל בהעברות של SQL בשבילכם.Data Connect אם תדחו את ההצעה, ל-Data Connect תהיה גישה רק ל-read ול-write בטבלאות של מסד הנתונים, אבל האחריות על בעלות על סכימות והעברות תישאר שלכם.

במאמר ניהול שירותים ומסדי נתונים יש מידע נוסף על הנושא ועל תרחישים לדוגמה.

dataconnect:sql:grant

firebase dataconnect:sql:grant

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

לפרטים על התפקידים שהוקצו, אפשר לעיין במאמר בנושא תפקידי משתמשים ב-PostgreSQL.

תפקיד תפקיד SQL הרשאות שימוש ניתן להעניק ‫Grantable
בעל הרשאת קריאה firebasereader_<db_name>_<schema_name> הרשאת קריאה בלבד למסד הנתונים.

יכול לבצע פעולות SELECT בכל הטבלאות בסכימה שצוינה.		 מתאים למשתמשים או לשירותים שנדרש להם אחזור נתונים אבל לא שינוי שלהם. כן
בעל הרשאת כתיבה firebasewriter_<db_name>_<schema_name> גישת קריאה וכתיבה למסד הנתונים.

יכול לבצע פעולות SELECT, INSERT, UPDATE, DELETE ו-TRUNCATE בכל הטבלאות בסכימה.		 מתאים למשתמשים או לשירותים שצריכים לשנות נתונים במסד הנתונים. כן
בעלים firebaseowner_<db_name>_<schema_name> הבעלים של הסכימה.

יש לו את כל ההרשאות בכל הטבלאות והרצפים בסכימה.		 התפקיד הזה, בשילוב עם התפקיד roles/cloudsql.client ב-IAM, מעניק הרשאה לביצוע העברה במסד הנתונים.

לדוגמה, כשמתקשרים אל firebase dataconnect:sql:migrate.		 כן
משתמש-מנהל cloudsqlsuperuser תפקיד מובנה של משתמש על עם הרשאות מלאות במסד הנתונים.

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

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

אם משתמש שאין לו הרשאות אדמין צריך הרשאות סופר-משתמש, ההעברה תיכשל והמשתמש יתבקש לבקש מאדמין מסד הנתונים (כלומר, משתמש עם הרשאה roles/cloudsql.admin) להריץ את פקודות ה-SQL עם ההרשאות.		 ההרשאה ניתנת למשתמשים עם roles/cloudsql.admin ואי אפשר להעניק אותה ישירות מ-Firebase CLI
Command תיאור

‫firebase dataconnect:sql:grant

דגל/פרמטר תיאור

‫‎-R, --role role

תפקיד ה-SQL להענקה, אחד מהתפקידים הבאים: בעלים, כתיבה או קריאה.

‫‎-E,‏ ‎--email email_address

כתובת האימייל של המשתמש או חשבון השירות שרוצים להקצות לו את התפקיד.

אפשרויות כלליות

האפשרויות הגלובליות הבאות חלות על כל הפקודות:

  • ‫--json מעביר את הפלט של ה-CLI ל-JSON לצורך ניתוח על ידי כלים אחרים.
  • --noninteractive ו---interactive כדי לבטל, לפי הצורך, את הזיהוי האוטומטי של סביבות שאינן TTY.