שמירת נתונים

כתיבת נתונים באמצעות PUT

פעולת הכתיבה הבסיסית דרך REST API היא PUT. כדי להדגים שמירת נתונים, נבנה אפליקציה לניהול בלוג עם פוסטים ומשתמשים. כל הנתונים של האפליקציה שלנו יאוחסנו בנתיב fireblog, בכתובת ה-URL של מסד הנתונים של Firebase‏ https://docs-examples.firebaseio.com/fireblog.

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

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

curl -X PUT -d '{
  "alanisawesome": {
    "name": "Alan Turing",
    "birthday": "June 23, 1912"
  }
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'

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

curl -X PUT -d '"Alan Turing"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'

curl -X PUT -d '"June 23, 1912"' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'

שתי הדוגמאות שלמעלה – כתיבת הערך בו-זמנית עם אובייקט וכתיבת הערכים בנפרד למיקומי צאצא – יובילו לשמירת אותם נתונים במסד הנתונים של Firebase:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing"
    }
  }
}

בקשה שמתבצעת בהצלחה תסומן באמצעות קוד סטטוס 200 OK של HTTP, והתשובה תכיל את הנתונים שכתבנו למסד הנתונים. בדוגמה הראשונה יופעל רק אירוע אחד בלקוחות שצופים בנתונים, ואילו בדוגמה השנייה יופעלו שני אירועים. חשוב לזכור שאם כבר היו נתונים בנתיב של המשתמש, הגישה הראשונה תדרוס אותם, אבל הגישה השנייה תשנה רק את הערך של כל צומת צאצא נפרד, בלי לשנות את שאר צומתי הצאצא. הפונקציה PUT שוות ערך לפונקציה set() ב-JavaScript SDK שלנו.

עדכון נתונים באמצעות PATCH

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

curl -X PATCH -d '{
  "nickname": "Alan The Machine"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

הבקשה שלמעלה תכתוב nickname לאובייקט alanisawesome שלנו בלי למחוק את הילדים name או birthday. שימו לב: אם היינו מגישים PUT בקשה כאן במקום זאת, name ו-birthday היו נמחקים כי הם לא נכללו בבקשה. הנתונים במסד הנתונים של Firebase נראים עכשיו כך:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    }
  }
}

בקשה שמתבצעת בהצלחה תסומן באמצעות קוד סטטוס 200 OK של HTTP, והתשובה תכיל את הנתונים המעודכנים שנכתבו במסד הנתונים.

ב-Firebase יש תמיכה גם בעדכונים של כמה נתיבים. המשמעות היא שמעכשיו אפשר לעדכן ערכים בכמה מיקומים במסד הנתונים של Firebase בו-זמנית. זו תכונה שימושית שעוזרת לכם לבצע דה-נורמליזציה של הנתונים.PATCH בעזרת עדכונים מרובי-נתיבים, אפשר להוסיף כינויים גם לאלן וגם לגרייס בו-זמנית:

curl -X PATCH -d '{
  "alanisawesome/nickname": "Alan The Machine",
  "gracehopper/nickname": "Amazing Grace"
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

אחרי העדכון הזה, הכינויים של אלן וגרייס נוספו:

{
  "users": {
    "alanisawesome": {
      "date_of_birth": "June 23, 1912",
      "full_name": "Alan Turing",
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "date_of_birth": "December 9, 1906",
      "full_name": "Grace Hopper",
      "nickname": "Amazing Grace"
    }
  }
}

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

curl -X PATCH -d '{
  "alanisawesome": {"nickname": "Alan The Machine"},
  "gracehopper": {"nickname": "Amazing Grace"}
}' \
  'https://docs-examples.firebaseio.com/fireblog/users.json'

התוצאה היא התנהגות שונה, כלומר דריסת הצומת /fireblog/users כולו:

{
  "users": {
    "alanisawesome": {
      "nickname": "Alan The Machine"
    },
    "gracehop": {
      "nickname": "Amazing Grace"
    }
  }
}

עדכון נתונים באמצעות בקשות מותנות

1. כדי לבצע בקשה מותנית במיקום מסוים, צריך לקבל את המזהה הייחודי של הנתונים הנוכחיים במיקום הזה, או את ה-ETag. אם הנתונים משתנים במיקום הזה, גם ה-ETag משתנה. אפשר לבקש ETag בכל שיטה חוץ מ-PATCH. בדוגמה הבאה נעשה שימוש בבקשת GET.

   curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

   קריאה ספציפית ל-ETag בכותרת מחזירה את ה-ETag של המיקום שצוין בתגובת ה-HTTP.

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   10 // Current value of the data at the specified location

2. כוללים את ה-ETag שהוחזר בבקשת PUT או DELETE הבאה כדי לעדכן נתונים שתואמים באופן ספציפי לערך ה-ETag הזה. בדוגמה שלנו, כדי לעדכן את המונה ל-11, כלומר ב-1 יותר מהערך ההתחלתי שחולץ (10), ולגרום לכך שהבקשה תיכשל אם הערך כבר לא תואם, צריך להשתמש בקוד הבא:

   curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match:[ETAG_VALUE]'

   אם הערך של הנתונים במיקום שצוין הוא עדיין 10, תג ה-ETag בבקשת PUT תואם, והבקשה מצליחה. הערך 11 נכתב במסד הנתונים.

   HTTP/1.1 200 OK
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   Cache-Control: no-cache
   
   11 // New value of the data at the specified location, written by the conditional request

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

   HTTP/1.1 412 Precondition Failed
   Content-Length: 6
   Content-Type: application/json; charset=utf-8
   Access-Control-Allow-Origin: *
   ETag: [ETAG_VALUE]
   Cache-Control: no-cache
   
   12 // New value of the data at the specified location

3. אם תחליטו לנסות שוב לשלוח את הבקשה, תוכלו להשתמש במידע החדש. Realtime Database לא מנסה אוטומטית לבצע שוב בקשות מותנות שנכשלו. עם זאת, אפשר להשתמש בערך החדש וב-ETag כדי ליצור בקשה מותנית חדשה עם המידע שמוחזר בתגובת השגיאה.

בקשות מותנות מבוססות REST מיישמות את התקן if-match של HTTP. עם זאת, יש ביניהם הבדלים מהסטנדרט:

• אפשר לציין רק ערך ETag אחד לכל בקשת if-match, ולא כמה ערכים.
• למרות שהתקן מציע להחזיר תגי ETags עם כל הבקשות, ב-Realtime Database מוחזרים תגי ETags רק עם בקשות שכוללות את הכותרת X-Firebase-ETag. כך אפשר להפחית את עלויות החיוב על בקשות רגילות.

יכול להיות שגם בקשות מותנות יהיו איטיות יותר מבקשות REST רגילות.

שמירת רשימות של נתונים

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

curl -X POST -d '{
  "author": "alanisawesome",
  "title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'

בנתיב posts יש עכשיו את הנתונים הבאים:

{
  "posts": {
    "-JSOpn9ZC54A4P4RoqVa": {
      "author": "alanisawesome",
      "title": "The Turing Machine"
    }
  }
}

שימו לב שהמפתח -JSOpn9ZC54A4P4RoqVa נוצר אוטומטית כי השתמשנו בבקשת POST. בקשה שמתבצעת בהצלחה תסומן באמצעות קוד סטטוס 200 OK של HTTP, והתגובה תכיל את המפתח של הנתונים החדשים שנוספו:

{"name":"-JSOpn9ZC54A4P4RoqVa"}

הסרת נתונים

כדי להסיר נתונים ממסד הנתונים, אפשר לשלוח בקשת DELETE עם כתובת ה-URL של הנתיב שממנו רוצים למחוק נתונים. הפקודה הבאה תמחק את אלן מהנתיב users:

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

בקשת DELETE מוצלחת תסומן על ידי קוד סטטוס HTTP‏ 200 OK עם תגובה שמכילה JSON‏ null.

פרמטרים של URI

ה-API ל-REST מקבל את פרמטרי ה-URI הבאים כשכותבים נתונים למסד הנתונים:

אימות

פרמטר הבקשה auth מאפשר גישה לנתונים שמוגנים על ידי Firebase Realtime Database Security Rules, והוא נתמך בכל סוגי הבקשות. הארגומנט יכול להיות הסוד של אפליקציית Firebase או אסימון אימות, שנסביר עליו בקטע הרשאת משתמש. בדוגמה הבאה אנחנו שולחים בקשת POST עם פרמטר auth, כאשר CREDENTIAL הוא הסוד של אפליקציית Firebase או טוקן אימות:

curl -X POST -d '{"Authenticated POST request"}' \
  'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

הדפס

הפרמטר print מאפשר לנו לציין את פורמט התשובה ממסד הנתונים. הוספת print=pretty לבקשה תחזיר את הנתונים בפורמט קריא. print=pretty נתמך על ידי בקשות של GET,‏ PUT,‏ POST,‏ PATCH ו-DELETE.

כדי להשתיק את הפלט מהשרת כשכותבים נתונים, אפשר להוסיף את המחרוזת print=silent לבקשה. אם הבקשה תצליח, התגובה שתתקבל תהיה ריקה ותצוין על ידי קוד סטטוס 204 No Content של HTTP. הבקשות print=silent נתמכות על ידי GET,‏ PUT,‏ POST ו-PATCH.

כתיבת ערכים של שרת

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

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'

‫"timestamp" הוא ערך השרת הנתמך היחיד, והוא מייצג את הזמן מאז ראשית זמן יוניקס (Unix epoch) במילישניות.

שיפור ביצועי כתיבה

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

במקרים שבהם אנחנו שולחים הרבה בקשות למסד הנתונים, אנחנו יכולים לעשות שימוש חוזר בחיבור ה-HTTPS על ידי שליחת בקשת Keep-Alive בכותרת ה-HTTP.

תנאי שגיאה

בנסיבות הבאות, ה-API ל-REST יחזיר קודי שגיאה:

אבטחת נתונים

ב-Firebase יש שפת אבטחה שמאפשרת לנו להגדיר אילו משתמשים יכולים לקרוא ולכתוב נתונים בצמתים שונים של הנתונים שלנו. מידע נוסף זמין במאמר בנושא Realtime Database Security Rules.