واجهة برمجة تطبيقات REST لقاعدة بيانات Firebase

استخدام واجهة برمجة التطبيقات

يمكنك استخدام أي عنوان URL لقاعدة بيانات Firebase في الوقت الفعلي كنقطة نهاية REST. كل ما عليك فعله هو إلحاق .json بنهاية عنوان URL وإرسال طلب من برنامج HTTPS المفضّل لديك.

يجب استخدام بروتوكول HTTPS. يستجيب Firebase فقط للزيارات المشفّرة، لتظل بياناتك آمنة.

GET - قراءة البيانات

يمكن قراءة البيانات من Realtime Database من خلال إصدار بروتوكول HTTP. طلب GET إلى نقطة نهاية. المثال التالي كيف يمكنك استرداد الصفحة التي الذي سبق لك تخزينه في Realtime Database. 

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

يُشار إلى الطلب الناجح باستخدام 200 OK HTTP رمز الحالة. يحتوي الرد على البيانات المرتبطة المسار في طلب GET. 

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

PUT - كتابة البيانات

يمكنك كتابة البيانات من خلال طلب PUT. 

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

يُشار إلى الطلب الناجح باستخدام 200 OK HTTP رمز الحالة. يحتوي الرد على البيانات المحددة في طلب "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، ولكن يتم حذفها لا يتم حذف الأطفال. ويعادل هذا الرمز JavaScript update(). 

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

يُشار إلى الطلب الناجح من خلال حالة HTTP 200 OK الرمز. يحتوي الرد على البيانات المحددة في طلب "PATCH". 

{ "last": "Jones" }

DELETE - إزالة البيانات

يمكنك حذف البيانات من خلال طلب 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 أيضًا. يجب تحديد علامة Firebase ETag في لطلب 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_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: <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: <ETag_of_null> لا ينطبق علامة ETag: <database_ETag>

مَعلمات طلب البحث

تقبل واجهة برمجة تطبيقات REST لقاعدة بيانات Firebase معلَمات طلب البحث التالية القيم التالية:

access_token

متوافقة مع جميع أنواع الطلبات يصادق على هذا الطلب للسماح الوصول إلى البيانات المحمية بواسطة Firebase Realtime Database Security Rules. يمكنك الاطّلاع على مستندات مصادقة 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 الوصف
جميل GET وPUT وPOST وPATCH وDELETE عرض البيانات بتنسيق يمكن لشخص عادي قراءته
صامت GET وPUT وPOST وPATCH يُستخدم لإيقاف الإخراج من الخادم عند كتابة البيانات. سيكون الرد الناتج فارغًا ويشار إليه بما يلي: رمز حالة HTTP 204 No Content. 
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 البيانات التي تم إرجاعها في دالة رد الاتصال التي تحددها. 

<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 على أنها tiny (target=1s)، small (target=10s)، medium (الاستهداف=30 ثانية)، large (الاستهداف=60 ثانية) تقدِّر قاعدة البيانات في الوقت الفعلي حجم كل طلب كتابة وعمليات الإلغاء. الطلبات التي ستستغرق وقتًا أطول من الوقت المستهدف.

في حال تحديد unlimited، ستتم عمليات كتابة كبيرة جدًا (مع حمولة تصل إلى 256 ميغابايت) من الممكن أن تحظر الطلبات اللاحقة أثناء معالجة قاعدة البيانات العملية الحالية. لا يمكن إلغاء عمليات الكتابة بعد وصولها إلى الخادم. 

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. وينطبق هذا الحدّ على جميع الطلبات، بما في ذلك الطلبات الواردة من حِزم تطوير البرامج (SDK). تم إنشاء قواعد بيانات جديدة مع ضبط defaultWriteSizeLimit على large. لا يمكنك ضبط defaultWriteSizeLimit على tiny باستخدام واجهة سطر الأوامر في Firebase. 

firebase database:settings:set defaultWriteSizeLimit large

orderBy

راجِع القسم في الدليل حول بيانات مرتّبة لمزيد من المعلومات.

limitToFirst،limitToLast، startAt، endAt، equalTo

راجِع القسم في الدليل حول تصفية البيانات بالنسبة إلى مزيد من المعلومات.

جارٍ البث من واجهة برمجة تطبيقات REST

تدعم نقاط نهاية Firebase REST EventSource / الأحداث المُرسَلة من الخادم والبروتوكول. لبث التغييرات إلى موقع واحد في Realtime Database، يُرجى اتّباع الخطوات التالية: تحتاج إلى القيام ببعض الأشياء:

  • ضبط عنوان "قبول" للعميل على "text/event-stream"
  • يجب احترام عمليات إعادة توجيه HTTP، ولا سيما رمز حالة HTTP 307
  • إذا كان الموقع الجغرافي يتطلب إذنًا للقراءة، عليك تضمين مَعلمة auth

وفي المقابل، سيرسل الخادم الأحداث المسماة كحالة البيانات في تغييرات عناوين URL المطلوبة. يتوافق هيكل هذه الرسائل مع إلى بروتوكول EventSource. 

event: event name
data: JSON encoded data payload

قد يرسل الخادم الأحداث التالية:

وضع

البيانات المرمّزة بترميز JSON هي كائن به مفتاحان: path والبيانات. يشير المسار الرئيسي إلى الموقع بالنسبة إلى عنوان URL للطلب. يجب على العميل استبدال جميع البيانات في هذا الموقع في ذاكرة التخزين المؤقت مع data.

رمز تصحيح

البيانات المرمّزة بترميز JSON هي كائن به مفتاحان: path والبيانات. يشير المسار الرئيسي إلى الموقع بالنسبة إلى عنوان URL للطلب. لكل مفتاح في data، على العميل استبدال المفتاح المقابل في ذاكرة التخزين المؤقت الخاصة به مع بيانات هذا المفتاح في الرسالة.

البقاء على قيد الحياة

بيانات هذا الحدث هي null. ليس عليك اتّخاذ أي إجراء.

إلغاء

يمكن أن تؤدي بعض الأخطاء غير المتوقّعة إلى إرسال حدث "إلغاء" وإنهاء الاتصال. يتم توضيح السبب في البيانات المقدَّمة لهذا الحدث. إن بعض الأسباب المحتملة هي التالي: 1- لم يعد Firebase Realtime Database Security Rules يسمح بالقراءة في الموقع المطلوب. تشير رسالة الأشكال البيانية وصف "البيانات" لهذا السبب هو "تم رفض الإذن". 2- أدّى عملية كتابة إلى تشغيل أداة بث الأحداث التي أرسلت شجرة JSON كبيرة تتجاوز الحدّ الأقصى المسموح به. 512 ميغابايت. البيانات الخاصة بهذا السبب هي "الحمولة المحددة كبيرة جدًا. يُرجى طلب موقع ببيانات أقل".

تم إلغاء المصادقة

وتكون بيانات هذا الحدث عبارة عن سلسلة تشير إلى أن بيانات الاعتماد منتهي الصلاحية. يتم إرسال هذا الحدث عند إدخال السمة 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 Realtime Database Security Rules" وتحديثه

كما يمكن استخدام واجهة برمجة تطبيقات REST لاسترداد وتحديث Firebase Realtime Database Security Rules عن لمشروعك في 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 تلقائيًا بدون مصادقة ولن تنجح إلا إذا تم قواعد Realtime Database تسمح للجميع بالوصول للقراءة أو الكتابة إلى البيانات. لمصادقة طلبك، استخدم مَعلمات طلب البحث access_token= أو auth=

مزيد من المعلومات حول المصادقة من خلال واجهة برمجة تطبيقات REST في مصادقة طلبات REST

حالات الخطأ

يمكن لواجهة برمجة تطبيقات REST في Firebase عرض رموز الخطأ التالية.

رموز حالة HTTP
400 طلب سيئ

أحد حالات الخطأ التالية:

  • يتعذّر تحليل بيانات PUT أو POST.
  • بيانات PUT أو POST غير متوفّرة.
  • يحاول الطلب الحصول على بيانات PUT أو POST. إنه كبير جدًا.
  • يحتوي طلب بيانات من واجهة برمجة التطبيقات REST على أسماء فرعية غير صالحة كجزء من المسار.
  • مسار طلب واجهة برمجة التطبيقات REST طويل جدًا.
  • يحتوي الطلب على قيمة خادم غير معروفة.
  • لم يتم تحديد فهرس طلب البحث في Firebase Realtime Database Security Rules
  • لا يتيح الطلب استخدام إحدى معلَمات طلب البحث المحدّدة.
  • يمزج الطلب بين معلَمات طلب البحث وطلب GET سطحي.
401 غير مصرَّح به

أحد حالات الخطأ التالية:

  • انتهت صلاحية رمز المصادقة.
  • الرمز المميز للمصادقة المستخدم في الطلب غير صالح.
  • تعذّرت المصادقة باستخدام access_token.
  • ينتهك الطلب Firebase Realtime Database Security Rules
404 لم يتم العثور على الصفحة لم يتم العثور على Realtime Database المحدد.
500 خطأ في الخادم الداخلي عرَض الخادم خطأ. راجِع رسالة الخطأ لمعرفة المزيد التفاصيل.
503 الخدمة غير متاحة قاعدة بيانات Firebase في الوقت الفعلي غير متاحة مؤقتًا، ما يعني أنّه لم تتم محاولة إرسال الطلب.
412 تعذّر إكمال الشرط المُسبَق. لم تتطابق قيمة ETag المحددة للطلب في عنوان if-match مع قيمة الخادم.