قاعدة بيانات Firebase REST API

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

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

مطلوب HTTPS. يستجيب Firebase فقط لحركة المرور المشفرة حتى تظل بياناتك آمنة.

الحصول على - قراءة البيانات

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

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

ما بعد - دفع البيانات

لإنجاز ما يعادل أسلوب JavaScript push() (راجع قوائم البيانات )، يمكنك إصدار طلب 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 ، ولكن لا يتم حذف العناصر الفرعية المحذوفة. وهذا يعادل وظيفة 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 أيضًا. يجب تحديد Firebase ETag في رأس طلب REST الأولي (عادةً GET ، ولكن يمكن أن يكون أي شيء آخر غير PATCH ).

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

إذا المباراة

يحدد شرط if-match قيمة ETag للبيانات التي تريد تحديثها. إذا استخدمت الشرط، فإن قاعدة بيانات الوقت الفعلي تكمل فقط الطلبات التي تتطابق فيها علامة ETag المحددة في طلب الكتابة مع ETag للبيانات الموجودة في قاعدة البيانات. قم بإحضار ETag في موقع باستخدام طلب Firebase ETag. إذا كنت تريد الكتابة فوق أي موقع فارغ، فاستخدم 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: صحيح" تطابقات ETag
if_match: <matching etag>
ETag غير متطابق
if_match: <no matching etag>
يحصل حالة الاستجابة/المحتوى 200: "<data_at_path>" 400: "...غير مدعوم.." 400: "...غير مدعوم.."
الرؤوس المضافة العلامة الإلكترونية: <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_of_post_data> لا يوجد لا يوجد
رقعة حالة الاستجابة/المحتوى 400: "...غير مدعوم.." 400: "...غير مدعوم.." 400: "...غير مدعوم.."
الرؤوس المضافة لا يوجد لا يوجد لا يوجد
يمسح حالة الاستجابة/المحتوى 200: لاغية 200: "<data_after_put>" 412: "...عدم تطابق علامة Etag.."
الرؤوس المضافة ETag: <ETag_of_null> لا يوجد علامة ETag: <database_ETag>

معلمات الاستعلام

تقبل Firebase Database REST API معلمات وقيم الاستعلام التالية:

رمز وصول

مدعومة بجميع أنواع الطلب. يصادق على هذا الطلب للسماح بالوصول إلى البيانات المحمية بواسطة قواعد أمان قاعدة بيانات Firebase Realtime. راجع وثائق مصادقة REST للحصول على التفاصيل.

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

أجوف

هذه ميزة متقدمة، مصممة لمساعدتك على العمل مع مجموعات البيانات الكبيرة دون الحاجة إلى تنزيل كل شيء. اضبط هذا على true للحد من عمق البيانات التي يتم إرجاعها في الموقع. إذا كانت البيانات الموجودة في الموقع عبارة عن بيانات JSON أولية (سلسلة أو رقم أو قيمة منطقية)، فسيتم إرجاع قيمتها ببساطة. إذا كانت لقطة البيانات في الموقع عبارة عن كائن JSON، فسيتم اقتطاع قيم كل مفتاح إلى true .

الحجج طرق الراحة وصف
أجوف يحصل الحد من عمق الاستجابة.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

لاحظ أنه لا يمكن خلط shallow مع أي معلمات استعلام أخرى.

مطبعة

تنسيق البيانات التي يتم إرجاعها في الاستجابة من الخادم.

الحجج طرق الراحة وصف
جميل الحصول على، وضع، نشر، التصحيح، الحذف عرض البيانات بتنسيق يمكن قراءته بواسطة الإنسان.
صامتة الحصول على، وضع، نشر، التصحيح يستخدم لمنع الإخراج من الخادم عند كتابة البيانات. ستكون الاستجابة الناتجة فارغة ويُشار إليها برمز حالة 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 API يغلف البيانات التي تم إرجاعها في وظيفة رد الاتصال التي تحددها.

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

شكل

إذا تم التعيين على export ، فسيقوم الخادم بتشفير الأولويات في الاستجابة.

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

firebase database:settings:set defaultWriteSizeLimit large

ترتيب حسب

راجع القسم الموجود في الدليل الخاص بالبيانات المطلوبة لمزيد من المعلومات.

LimitToFirst، LimitToLast، startAt، endAt، يساوي

راجع القسم الموجود في الدليل الخاص بتصفية البيانات لمزيد من المعلومات.

البث من REST API

تدعم نقاط نهاية Firebase REST بروتوكول EventSource / Server-Sent Events . لدفق التغييرات إلى موقع واحد في قاعدة بيانات Realtime، يتعين عليك القيام ببعض الأشياء:

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

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

event: event name
data: JSON encoded data payload

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

يضع

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

رقعة

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

حافظ على حياتك

بيانات هذا الحدث null . لا يلزم اتخاذ أي إجراء.

يلغي

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

auth_revoced

بيانات هذا الحدث عبارة عن سلسلة تشير إلى انتهاء صلاحية بيانات الاعتماد. يتم إرسال هذا الحدث عندما تصبح معلمة 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

يمكن أيضًا استخدام REST API لاسترداد وتحديث قواعد أمان قاعدة بيانات Firebase Realtime لمشروع 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= .

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

شروط الخطأ

يمكن لـ Firebase Database REST API إرجاع رموز الخطأ التالية.

رموز حالة HTTP
400 طلب سىء

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

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

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

404 غير موجود لم يتم العثور على قاعدة بيانات الوقت الفعلي المحددة.
500 خطأ داخلي في الخادم أرجع الخادم خطأً. راجع رسالة الخطأ لمزيد من التفاصيل.
503 الخدمة غير متوفرة قاعدة بيانات Firebase Realtime المحددة غير متاحة مؤقتًا، مما يعني أنه لم تتم محاولة الطلب.
412 فشل الشرط المسبق لم تتطابق قيمة ETag المحددة للطلب في رأس if-match مع قيمة الخادم.