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

ה-CLI של Firebase הוא כלי שמאפשר לנהל ולהגדיר מוצרים ושירותים של 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 ל-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

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

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

ב-Data Connect יש שלוש גישות לייצוא/ייבוא:

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

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

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

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

בזמן שהמכונה הווירטואלית של Data Connect פועלת, מריצים את הפקודה firebase emulators:export במסוף נפרד כדי לשמור קובץ snapshot של הנתונים. לאחר מכן, אפשר להפעיל את הסימולטור מהקובץ המצולם באמצעות הדגל --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, בזמן שהאמולטור פועל, לוחצים על הלחצן Export emulator data כדי לייצא את תוכן מסד הנתונים הנוכחי. מיקום הייצוא שמוגדר כברירת מחדל הוא הספרייה 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, אפשר לציין כמה שירותים ולהפריד ביניהם בפסיקים.

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

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

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

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

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

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

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

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

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

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

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

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

כשפורסים את המחברים, ה-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

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

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

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

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

dataconnect:sql:grant

firebase dataconnect:sql:grant

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

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

תפקיד תפקיד SQL הרשאות שימוש ניתן להקצות
קורא 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, ולא ניתן להעניק אותה ישירות מ-CLI של Firebase
Command תיאור

firebase dataconnect:sql:grant

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

-R,‏ --role role

תפקיד ה-SQL שרוצים להקצות, מתוך: owner,‏ writer או reader.

‎-E, --email email_address

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

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

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

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