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

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 שמוגדרת בו ברירת המחדל, הפקודה dataconect: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 מחיל שינויים תואמים ומציג הודעה לפני ביצוע שינויים מחמירים. מקור המידע בנושא הגדרות

פקודות 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

dataconnect:sql:grant

firebase dataconnect:sql:grant

Data Connect פועל מעל למכונה שלכם ב-PostgreSQL שמתארח ב-Cloud SQL. במקרים מסוימים, יכול להיות שתרצו לגשת ישירות למסד הנתונים כדי להריץ שאילתות או לעדכן את הנתונים שנוצרו על ידי האפליקציות של 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.