דף זה תורגם על ידי Cloud Translation API.

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

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

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

פקודות הגדרה

הוספת 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

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

הייצוא נשמר כתמונות מצב של מסד הנתונים המקומי של 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, בזמן שהאמולטור פועל, לוחצים על הלחצן Export emulator data (ייצוא נתוני האמולטור) כדי לייצא את התוכן הנוכחי של מסד הנתונים. מיקום הייצוא שמוגדר כברירת מחדל הוא הספרייה exportedData בספריית הבסיס של הפרויקט.

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

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

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

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

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

לפרוס

firebase deploy

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

‫Command	תיאור
firebase deploy	Flag	תיאור
	–-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	Flag	תיאור
	serviceId	מעבירים את מסד הנתונים לשירות שצוין. המערכת מסיקה את serviceId אם בפרויקט יש רק שירות אחד.
	‪--force	אישור אוטומטי של הנחיות.

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

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

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

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

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

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

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

הערכת ההשפעה	תרחיש
רמת אזהרה (תואם לחיבור קווי, יכול להיות שההתנהגות תשתנה)	הסרת שדה שניתן להגדרה כ-nullable משאילתה ללא הערה `@retired`.
שינוי שובר (לא תואם ל-wire, עלול לשבור לקוחות)	שינוי משתנה שניתן להקצות לו ערך 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	Flag	תיאור
	–-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), יכול להיות שיש לכם תהליך עבודה משלכם להעברת סכימות, ואתם רוצים לשמור על הבעלות על הסכימה בעצמכם. אם זה התהליך המועדף עליכם, הקפידו לסרב להצעה של Data Connect לטפל בהעברות של SQL בשבילכם בהנחיה dataconnect:sql:setup. אם תדחו את הבקשה, ל-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 להענקה, אחד מהתפקידים הבאים: בעלים, כתיבה או קריאה.
	‫‎-E,‏ ‎--email email_address	כתובת האימייל של המשתמש או חשבון השירות שרוצים להקצות לו את התפקיד.

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

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

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