משחזר נתונים

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

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

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

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

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

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

אישור

פרמטר בקשת auth מאפשר גישה לנתונים המוגנים על ידי Firebase Realtime Database Rules , והוא נתמך על ידי כל סוגי הבקשות. הארגומנט יכול להיות סוד אפליקציית 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 יהיו אובייקט עם שני מפתחות: נתיב ונתונים
הנתיב מצביע על מיקום ביחס לכתובת ה-URL של הבקשה
הלקוח צריך להחליף את כל הנתונים באותו מיקום במטמון שלו בנתונים המופיעים בהודעה
תיקון הנתונים המקודדים ב-JSON יהיו אובייקט עם שני מפתחות: נתיב ונתונים
הנתיב מצביע על מיקום ביחס לכתובת ה-URL של הבקשה
עבור כל מפתח בנתונים, הלקוח צריך להחליף את המפתח המתאים במטמון שלו בנתונים של אותו מפתח בהודעה
להשאיר בחיים הנתונים עבור אירוע זה הם אפסיים, אין צורך בפעולה
לְבַטֵל הנתונים עבור אירוע זה הם אפסיים
אירוע זה יישלח אם כללי מסד הנתונים של 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.