משחזר נתונים

קריאת נתונים עם GET

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

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

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

הוספת פרמטרי URI

REST API מקבל מספר פרמטרים של שאילתה בעת קריאת נתונים ממסד הנתונים שלנו ב-Firebase. להלן מפורטים הפרמטרים הנפוצים ביותר. לרשימה מלאה, עיין ב- REST API Reference .

אישור

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

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

הדפס

ציון print=pretty מחזיר את הנתונים בפורמט הניתן לקריאה אנושית.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

ציון print=silent מחזיר 204 No Content על הצלחה.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

התקשר חזרה

כדי לבצע שיחות REST מדפדפן אינטרנט בדומיינים, אתה יכול להשתמש ב-JSONP כדי לעטוף את התגובה בפונקציית התקשרות חוזרת של JavaScript. הוסף callback= כדי שה-REST API יעטוף את הנתונים המוחזרים בפונקציית ה-callback שתציין. לדוגמה:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

רָדוּד

זוהי תכונה מתקדמת, שנועדה לעזור לך לעבוד עם מערכי נתונים גדולים מבלי שתצטרך להוריד הכל. כדי להשתמש בו, הוסף shallow=true כפרמטר. זה יגביל את עומק הנתונים המוחזרים. אם הנתונים במיקום הם פרימיטיביים של JSON (מחרוזת, מספר או בוליאני) הערך שלהם פשוט יוחזר. אם תמונת המצב של הנתונים במיקום היא אובייקט JSON, הערכים של כל מפתח יקוצצו ל- true . לדוגמה, באמצעות הנתונים הבאים:

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

נסה את זה עם בקשת curl זו:

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

פסק זמן

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

ציין timeouts באמצעות הפורמט הבא: 3ms , 3s , או 3min , עם מספר ויחידה. אם לא צוין, timeout המרבי של 15min יוחל. אם timeout אינו חיובי, או חורג מהמקסימום, הבקשה תידחה עם שגיאת HTTP 400. בדוגמה הבאה, בקשת ה- GET כוללת timeout של 10 שניות.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

סינון נתונים

אנו יכולים לבנות שאילתות לסינון נתונים על סמך גורמים שונים. כדי להתחיל, אתה מציין כיצד אתה רוצה שהנתונים שלך יסוננו באמצעות הפרמטר orderBy . לאחר מכן, אתה משלב orderBy עם כל אחד מחמשת הפרמטרים האחרים: limitToFirst , limitToLast , startAt , endAt ו- equalTo .

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

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

אנו יכולים לסנן נתונים באחת משלוש דרכים: לפי מפתח צאצא , לפי מפתח , או לפי ערך . שאילתה מתחילה באחד מהפרמטרים הללו, ולאחר מכן יש לשלב אותה עם אחד או יותר מהפרמטרים הבאים: startAt , endAt , limitToFirst , limitToLast , או equalTo .

סינון לפי מפתח צאצא שצוין

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

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

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

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

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

כדי לשאול את הגובה כעת, אנו משתמשים בנתיב המלא לאובייקט במקום במפתח בודד:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

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

סינון לפי מפתח

אנו יכולים גם לסנן צמתים לפי המפתחות שלהם באמצעות הפרמטר orderBy="$key" . הדוגמה הבאה מאחזרת את כל הדינוזאורים עם שם שמתחיל באות a עד m :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

סינון לפי ערך

אנו יכולים לסנן צמתים לפי הערך של מפתחות הצאצא שלהם באמצעות הפרמטר orderBy="$value" . נניח שהדינוזאורים עורכים תחרות ספורט דינו ואנחנו עוקבים אחר התוצאות שלהם בפורמט הבא:

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

כדי לאחזר את כל הדינוזאורים עם ציון גבוה מ-50, נוכל להגיש את הבקשה הבאה:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

ראה כיצד הנתונים מסודרים לקבלת הסבר כיצד ממוינים ערכי null , בוליאני, מחרוזת ואובייקט בעת שימוש orderBy="$value" .

סינון מורכב

אנו יכולים לשלב מספר פרמטרים כדי לבנות שאילתות מורכבות יותר.

הגבלת שאילתות

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

באמצעות מסד הנתונים של עובדות הדינוזאורים שלנו ו- orderBy , נוכל למצוא את שני הדינוזאורים הכבדים ביותר:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

באופן דומה, אנו יכולים למצוא את שני הדינוזאורים הקצרים ביותר באמצעות limitToFirst :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

אנו יכולים גם לבצע שאילתות הגבלה באמצעות orderBy="$value" . אם ברצוננו ליצור לוח הישגים עם שלושת מתחרי הספורט הדינו בעלי הניקוד הגבוה ביותר, נוכל לעשות את הפעולות הבאות:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

שאילתות טווח

שימוש startAt , endAt ו- equalTo מאפשר לנו לבחור נקודות התחלה וסיום שרירותיות עבור השאילתות שלנו. לדוגמה, אם נרצה למצוא את כל הדינוזאורים שגובהם שלושה מטרים לפחות, נוכל לשלב orderBy ו- startAt :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

אנו יכולים להשתמש endAt כדי למצוא את כל הדינוזאורים ששמם בא לפני Pterodactyl מבחינה לקסיקוגרפית:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

אנו יכולים לשלב startAt ו- endAt כדי להגביל את שני הקצוות של השאילתה שלנו. הדוגמה הבאה מוצאת את כל הדינוזאורים ששמם מתחיל באות "ב":

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

שאילתות טווח שימושיות גם כאשר אתה צריך לדמיין את הנתונים שלך.

מחברים את הכל ביחד

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

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

כיצד מסודרים נתונים

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

מיין לפי

בעת שימוש orderBy עם שם של מפתח צאצא, נתונים המכילים את מפתח הצאצא שצוין יסודרו באופן הבא:

  1. ילדים עם ערך null עבור מפתח הצאצא שצוין קודמים.
  2. ילדים עם הערך של false עבור מפתח הצאצא שצוין מגיעים לאחר מכן. אם למספר ילדים יש ערך של false , הם ממוינים בלקסיקוגרפית לפי מפתח.
  3. ילדים עם הערך של true עבור מפתח הצאצא שצוין מגיעים לאחר מכן. אם למספר ילדים יש ערך של true , הם ממוינים בלקסיקוגרפית לפי מפתח.
  4. ילדים עם ערך מספרי מגיעים אחר כך, ממוינים בסדר עולה. אם למספר ילדים יש ערך מספרי זהה עבור צומת הצאצא שצוין, הם ממוינים לפי מפתח.
  5. מחרוזות באות אחרי מספרים, וממוינות בלקסיקוגרפית בסדר עולה. אם למספר ילדים יש אותו ערך עבור צומת הצאצא שצוין, הם מסודרים בלקסיקוגרפית לפי מפתח.
  6. אובייקטים מגיעים אחרונים, וממוינים בצורה לקסיקוגרפית לפי מפתח בסדר עולה.
התוצאות המסוננות מוחזרות ללא סדר. אם סדר הנתונים שלך חשוב, עליך למיין את התוצאות באפליקציה שלך לאחר החזרתן מ-Firebase.

orderBy="$key"

בעת שימוש בפרמטר orderBy="$key" למיון הנתונים שלך, הנתונים יוחזרו בסדר עולה לפי מפתח באופן הבא. זכור שמפתחות יכולים להיות רק מחרוזות.

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

orderBy="$value"

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

orderBy="$priority"

בעת שימוש בפרמטר orderBy="$priority" למיון הנתונים שלך, סדר הילדים נקבע לפי העדיפות והמפתח שלהם כדלקמן. זכור שערכי עדיפות יכולים להיות רק מספרים או מחרוזות.

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

למידע נוסף על סדרי עדיפויות, עיין בהפניה ל-API .

סטרימינג מ- REST API

נקודות הקצה של Firebase REST תומכות בפרוטוקול EventSource / Server-Sent Events , מה שמקל על הזרמת שינויים למיקום בודד במסד הנתונים של Firebase שלנו.

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

  1. הגדר את הכותרת Accept של הלקוח text/event-stream
  2. כבד את הפניות HTTP, במיוחד קוד סטטוס HTTP 307
  3. כלול את פרמטר שאילתת auth אם מיקום מסד הנתונים של Firebase דורש הרשאת קריאה

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

event: event name
data: JSON encoded data payload

השרת עשוי לשלוח את האירועים הבאים:

לָשִׂים הנתונים המקודדים ב-JSON יהיו אובייקט עם שני מפתחות: נתיב ונתונים
הנתיב מצביע על מיקום ביחס לכתובת האתר של הבקשה
הלקוח צריך להחליף את כל הנתונים באותו מיקום במטמון שלו בנתונים המופיעים בהודעה
תיקון הנתונים המקודדים ב-JSON יהיו אובייקט עם שני מפתחות: נתיב ונתונים
הנתיב מצביע על מיקום ביחס לכתובת האתר של הבקשה
עבור כל מפתח בנתונים, הלקוח צריך להחליף את המפתח המתאים במטמון שלו בנתונים של אותו מפתח בהודעה
להשאיר בחיים הנתונים עבור אירוע זה הם אפסיים, אין צורך בפעולה
לְבַטֵל הנתונים עבור אירוע זה הם אפסיים
אירוע זה יישלח אם כללי האבטחה של מסד הנתונים של Firebase בזמן אמת יגרמו לקריאה במיקום המבוקש לא להתאפשר עוד
auth_revoked הנתונים עבור אירוע זה הם מחרוזת המציינת שפג תוקפו של האישור
אירוע זה יישלח כאשר פרמטר האישור שסופק אינו תקף עוד

להלן דוגמה לקבוצת אירועים שהשרת עשוי לשלוח:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

אם אתה משתמש ב-Go, בדוק את Firego , מעטפת צד שלישי סביב ממשקי ה-API של Firebase REST ו-Streaming.