קריאת נתונים עם 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
עם שם מפתח צאצא, נתונים המכילים את מפתח הצאצא שצוין יסודרו באופן הבא:
- ילדים עם ערך
null
עבור מפתח הצאצא שצוין קודמים. - ילדים עם הערך של
false
עבור מפתח הצאצא שצוין מגיעים לאחר מכן. אם למספר ילדים יש ערך שלfalse
, הם ממוינים בלקסיקוגרפית לפי מפתח. - ילדים עם הערך של
true
עבור מפתח הצאצא שצוין מגיעים לאחר מכן. אם למספר ילדים יש ערך שלtrue
, הם ממוינים בלקסיקוגרפית לפי מפתח. - ילדים עם ערך מספרי מגיעים אחר כך, ממוינים בסדר עולה. אם למספר ילדים יש ערך מספרי זהה עבור צומת הצאצא שצוין, הם ממוינים לפי מפתח.
- מחרוזות באות אחרי מספרים, וממוינות בלקסיקוגרפית בסדר עולה. אם למספר ילדים יש ערך זהה עבור צומת הילד שצוין, הם מסודרים בלקסיקוגרפית לפי מפתח.
- אובייקטים מגיעים אחרונים, וממוינים בצורה לקסיקוגרפית לפי מפתח בסדר עולה.
orderBy="$key"
בעת שימוש בפרמטר orderBy="$key"
למיון הנתונים שלך, הנתונים יוחזרו בסדר עולה לפי מפתח באופן הבא. זכור שמפתחות יכולים להיות רק מחרוזות.
- ילדים עם מפתח שניתן לנתח כמספר שלם של 32 סיביות מגיעים ראשונים, ממוינים בסדר עולה.
- ילדים עם ערך מחרוזת כמפתח מגיעים אחר כך, ממוינים בלקסיוגרפית בסדר עולה.
orderBy="$value"
כאשר אתה משתמש בפרמטר orderBy="$value"
כדי למיין את הנתונים שלך, הילדים יסודרו לפי הערך שלהם. קריטריוני ההזמנה זהים לנתונים שהוזמנו על ידי מפתח צאצא, אלא שהערך של הצומת משמש במקום הערך של מפתח צאצא שצוין.
orderBy="$priority"
בעת שימוש בפרמטר orderBy="$priority"
למיון הנתונים שלך, סדר הילדים נקבע לפי העדיפות והמפתח שלהם כדלקמן. זכור שערכי עדיפות יכולים להיות רק מספרים או מחרוזות.
- ילדים ללא עדיפות (ברירת המחדל) קודמים.
- ילדים עם מספר בראש סדר העדיפויות שלהם מגיעים אחר כך. הם ממוינים מספרית לפי עדיפות, קטן עד גדול.
- ילדים עם מיתר בראש סדר העדיפויות שלהם. הם ממוינים לקסיקוגרפית לפי עדיפות.
- בכל פעם שלשני ילדים יש אותה עדיפות (כולל אין עדיפות), הם ממוינים לפי מפתח. מפתחות מספרים מגיעים תחילה (ממוינים מספרית), ואחריהם המקשים הנותרים (ממוינים בצורה לקסיקוגרפית).
למידע נוסף על סדרי עדיפויות, עיין בהפניה ל-API .
סטרימינג מ- REST API
נקודות הקצה של Firebase REST תומכות בפרוטוקול EventSource / Server-Sent Events , מה שמקל על הזרמת שינויים למיקום בודד במסד הנתונים של Firebase שלנו.
כדי להתחיל עם סטרימינג, נצטרך לעשות את הפעולות הבאות:
- הגדר את הכותרת Accept של הלקוח
text/event-stream
- כבד את הפניות HTTP, במיוחד קוד סטטוס HTTP 307
- כלול את פרמטר שאילתת
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.