Firebase Database REST API

שימוש ב-API

אתה יכול להשתמש בכל כתובת אתר של מסד נתונים של Firebase בזמן אמת כנקודת קצה של REST. כל מה שאתה צריך לעשות הוא לצרף .json לסוף כתובת האתר ולשלוח בקשה מלקוח ה-HTTPS המועדף עליך.

נדרש HTTPS. Firebase מגיב רק לתעבורה מוצפנת כך שהנתונים שלך נשארים בטוחים.

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

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

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

{ "first": "Jack", "last": "Sparrow" }

PUT - כתיבת נתונים

אתה יכול לכתוב נתונים עם בקשת PUT .

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

בקשה מוצלחת מסומנת על ידי קוד מצב HTTP 200 OK . התגובה מכילה את הנתונים שצוינו בבקשת ה- PUT .

{ "first": "Jack", "last": "Sparrow" }

POST - דחיפת נתונים

כדי להשיג את המקבילה לשיטת ה- push() של JavaScript (ראה רשימות נתונים ), אתה יכול להוציא בקשת POST .

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

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

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - עדכון נתונים

אתה יכול לעדכן ילדים ספציפיים במיקום מבלי להחליף נתונים קיימים באמצעות בקשת PATCH . ילדים בעלי שם בנתונים הנכתבים עם PATCH נמחקים, אך ילדים שהושמטו אינם נמחקים. זה שווה ערך לפונקציית JavaScript update() .

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

בקשה מוצלחת מסומנת על ידי קוד מצב HTTP 200 OK . התגובה מכילה את הנתונים שצוינו בבקשת ה- PATCH .

{ "last": "Jones" }

מחק - הסרת נתונים

אתה יכול למחוק נתונים באמצעות בקשת DELETE :

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

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

ביטול שיטה

אם אתה מבצע קריאות REST מדפדפן שאינו תומך בשיטות הקודמות, תוכל לעקוף את שיטת הבקשה על ידי ביצוע בקשת POST והגדרת השיטה שלך באמצעות כותרת הבקשה X-HTTP-Method-Override .

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

אתה יכול גם להשתמש בפרמטר השאילתה x-http-method-override .

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

בקשות על תנאי

בקשות מותנות, המקבילה ל-REST של פעולות עסקאות SDK, מעדכנות נתונים בהתאם לתנאי מסוים. ראה סקירה כללית של זרימת העבודה וקבל מידע נוסף על בקשות מותנות עבור REST בשמירת נתונים .

Firebase ETag

Firebase ETag הוא המזהה הייחודי של הנתונים הנוכחיים במיקום מוגדר. אם הנתונים משתנים במיקום זה, גם ה-ETag משתנה. יש לציין את ה-ETag של Firebase בכותרת עבור בקשת ה-REST הראשונית (בדרך כלל GET , אבל יכול להיות כל דבר אחר מלבד PATCH ).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

אם-התאמה

התנאי if-match מציין את ערך ה-ETag עבור הנתונים שברצונך לעדכן. אם אתה משתמש בתנאי, Realtime Database משלים רק בקשות שבהן ה-ETag שצוין בבקשת הכתיבה תואם ל-ETag של הנתונים הקיימים במסד הנתונים. אחזר את ה-ETag במיקום עם בקשת ETag של Firebase. אם אתה רוצה להחליף כל מיקום שהוא null, השתמש null_etag .

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

תגובות צפויות

הטבלה הבאה מספקת סקירה כללית של התגובות הצפויות עבור כל סוג בקשה, בהתבסס על התאמת ה-ETag.

סוג בקשה 'X-Firebase-ETag: true' התאמות Etag
if_match: <matching etag>		 ETag לא תואם
if_match: <no matching etag>
לקבל סטטוס תגובה/תוכן 200: "<data_at_path>" 400: "...לא נתמך.." 400: "...לא נתמך.."
נוספו כותרות ETag: <ETag_of_data> לא לא
לָשִׂים סטטוס תגובה/תוכן 200: "<put_data>" 200: "<put_data>" 412: "...אי התאמה של תג.."
נוספו כותרות ETag: <ETag_of_put_data> לא ETag: <database_ETag>
הודעה סטטוס תגובה/תוכן 200: "<post_data>" 400: "...לא נתמך.." 400: "...לא נתמך.."
נוספו כותרות ETag: <ETag_of_post_data> לא לא
תיקון סטטוס תגובה/תוכן 400: "...לא נתמך.." 400: "...לא נתמך.." 400: "...לא נתמך.."
נוספו כותרות לא לא לא
לִמְחוֹק סטטוס תגובה/תוכן 200: ריק 200: "<data_after_put>" 412: "...אי התאמה של תג.."
נוספו כותרות ETag: <ETag_of_null> לא ETag: <database_ETag>

פרמטרי שאילתה

Firebase Database REST API מקבל את הפרמטרים והערכים הבאים של השאילתה:

אסימון גישה

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

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

רָדוּד

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

טיעונים שיטות REST תיאור
רָדוּד לקבל הגבל את עומק התגובה.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

שים לב שלא ניתן לערבב shallow עם פרמטרים אחרים של שאילתה.

הדפס

פורמט את הנתונים המוחזרים בתגובה מהשרת.

טיעונים שיטות REST תיאור
יפה קבל, הכנס, פרסם, תיקון, מחק הצג את הנתונים בפורמט הניתן לקריאה אנושית.
שקט קבל, שים, פרסם, תיקון משמש לדיכוי הפלט מהשרת בעת כתיבת נתונים. התגובה שתתקבל תהיה ריקה ותצוין על ידי קוד סטטוס 204 No Content HTTP.
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

התקשר חזרה

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

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

פוּרמָט

אם מוגדר export , השרת יקודד עדיפויות בתגובה.

טיעונים שיטות REST תיאור
יְצוּא לקבל כלול מידע עדיפות בתגובה.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

הורד

נתמך על ידי GET בלבד. אם תרצה להפעיל הורדת קובץ של הנתונים שלך מדפדפן אינטרנט, הוסף download= . זה גורם לשירות REST להוסיף את הכותרות המתאימות כדי שדפדפנים ידעו לשמור את הנתונים בקובץ.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

פסק זמן

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

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

writeSizeLimit

כדי להגביל את גודל הכתיבה, אתה יכול לציין את פרמטר השאילתה writeSizeLimit tiny (target=1s), small (target=10s), medium (target=30s), large (target=60s). מסד נתונים בזמן אמת מעריך את הגודל של כל בקשת כתיבה ומבטל בקשות שייקחו יותר מזמן היעד.

אם תציין unlimited , מותרות כתיבה גדולה במיוחד (עם עומס של עד 256MB), מה שעלול לחסום בקשות עוקבות בזמן שמסד הנתונים מעבד את הפעולה הנוכחית. לא ניתן לבטל כתיבה לאחר שהן מגיעות לשרת.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

תראה את הודעת השגיאה הבאה אם ​​הכתיבה גדולה מדי:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

בנוסף, אתה יכול להגדיר את defaultWriteSizeLimit עבור כל מופע מסד הנתונים באמצעות Firebase CLI. מגבלה זו חלה על כל הבקשות, כולל אלה מ-SDKs. מסדי נתונים חדשים נוצרים עם defaultWriteSizeLimit מוגדר large . אינך יכול להגדיר defaultWriteSizeLimit tiny באמצעות Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

מיין לפי

עיין בסעיף במדריך על נתונים מוזמנים למידע נוסף.

limitToFirst, limitToLast, startAt, endAt, equalTo

עיין בסעיף במדריך על סינון נתונים למידע נוסף.

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

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

  • הגדר את הכותרת Accept של הלקוח "text/event-stream"
  • כבד את הפניות HTTP, במיוחד קוד סטטוס HTTP 307
  • אם המיקום דורש הרשאת קריאה, עליך לכלול את פרמטר auth

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

event: event name
data: JSON encoded data payload

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

לָשִׂים

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

תיקון

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

להשאיר בחיים

הנתונים עבור אירוע זה הם null . אין צורך בפעולה.

לְבַטֵל

כמה שגיאות בלתי צפויות יכולות לשלוח אירוע 'ביטול' ולסיים את החיבור. הסיבה מתוארת בנתונים שסופקו לאירוע זה. כמה סיבות אפשריות הן כדלקמן: 1. כללי האבטחה של מסד הנתונים של Firebase בזמן אמת אינם מאפשרים עוד קריאה במיקום המבוקש. תיאור `נתונים` עבור סיבה זו הוא "הרשאה נדחתה". 2. כתיבה הפעילה סטרימר אירועים ששלח עץ JSON גדול שחורג מהמגבלה שלנו, 512MB. `הנתונים` עבור סיבה זו הם "העומס שצוין גדול מדי, אנא בקש מיקום עם פחות נתונים."

auth_revoked

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

להלן סט דוגמה של אירועים שהשרת עשוי לשלוח:

// 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}}

סדרי עדיפויות

ניתן להפנות למידע עדיפות עבור מיקום עם "ילד וירטואלי" בשם .priority . אתה יכול לקרוא סדרי עדיפויות עם בקשות GET ולכתוב אותם עם בקשות PUT . לדוגמה, הבקשה הבאה מאחזרת את העדיפות של צומת users/tom :

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

כדי לכתוב עדיפות ונתונים בו-זמנית, אתה יכול להוסיף ילד .priority למטען ה-JSON:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

כדי לכתוב עדיפות וערך פרימיטיבי (למשל מחרוזת) בו-זמנית, אתה יכול להוסיף ילד .priority ולשים את הערך הפרימיטיבי בילד .value :

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

זה כותב "Tom" עם עדיפות של 1.0 . ניתן לכלול עדיפויות בכל עומק במטען ה-JSON.

ערכי שרת

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

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

אתה יכול גם לכתוב סדרי עדיפויות באמצעות ערכי שרת, באמצעות הנתיב "ילד וירטואלי" שצוין למעלה.

ערכי שרת נתמכים כוללים:

ערך שרת
חותמת זמן הזמן מאז עידן UNIX, באלפיות שניות.
תוֹסֶפֶת ספק ערך דלתא של מספר שלם או נקודה צפה, בצורה { ".sv": {"increment": <delta_value> }} , שבאמצעותו ניתן להגדיל באופן אטומי את ערך מסד הנתונים הנוכחי. אם הנתונים עדיין לא קיימים, העדכון יקבע את הנתונים לערך הדלתא. אם אחד מערכי הדלתא או הנתונים הקיימים הם מספרי נקודה צפה, שני הערכים יתפרשו כמספרי נקודה צפה ויוחלו בקצה האחורי כערך כפול. אריתמטיקה כפולה וייצוג של ערכים כפולים עוקבים אחר סמנטיקה של IEEE 754. אם יש הצפת מספר שלם חיובי/שלילי, הסכום מחושב כפול.

אחזור ועדכון כללי האבטחה של מסדי נתונים של Firebase בזמן אמת

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

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

אימות בקשות

כברירת מחדל, בקשות REST מבוצעות ללא אימות והן יצליחו רק אם כללי מסד הנתונים בזמן אמת מאפשרים גישת קריאה או כתיבה ציבורית לנתונים. כדי לאמת את בקשתך, השתמש בפרמטרי השאילתה access_token= או auth= .

למד עוד על אימות דרך ממשק ה-API של REST ב -אמת בקשות REST .

תנאי שגיאה

Firebase Database REST API יכול להחזיר את קודי השגיאה הבאים.

קודי מצב HTTP
בקשה שגויה 400

אחד מתנאי השגיאה הבאים:

  • לא ניתן לנתח נתוני PUT או POST .
  • חסרים נתוני PUT או POST .
  • הבקשה מנסה PUT או POST נתונים גדולים מדי.
  • הקריאה ל-REST API מכילה שמות צאצאים לא חוקיים כחלק מהנתיב.
  • נתיב הקריאה של REST API ארוך מדי.
  • הבקשה מכילה ערך שרת לא מזוהה.
  • האינדקס עבור השאילתה אינו מוגדר בכללי האבטחה של מסד הנתונים של Firebase בזמן אמת .
  • הבקשה אינה תומכת באחד מפרמטרי השאילתה שצוינו.
  • הבקשה מערבבת פרמטרים של שאילתה עם בקשת GET רדודה.
401 לא מורשה

אחד מתנאי השגיאה הבאים:

404 לא נמצא מסד הנתונים בזמן אמת לא נמצא.
500 שגיאת שרת פנימית השרת החזיר שגיאה. עיין בהודעת השגיאה לפרטים נוספים.
שירות 503 אינו זמין מסד הנתונים בזמן אמת של Firebase שצוין אינו זמין באופן זמני, מה שאומר שהבקשה לא נוסתה.
412 תנאי מוקדם נכשל ערך ה-ETag שצוין של הבקשה בכותרת if-match לא תאם את ערך השרת.