استخدام واجهة برمجة التطبيقات
يمكنك استخدام أي عنوان 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: صحيح" | تطابقات ETagif_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 طلب سىء | أحد حالات الخطأ التالية:
|
401 غير مصرح به | أحد حالات الخطأ التالية:
|
404 غير موجود | لم يتم العثور على قاعدة بيانات الوقت الفعلي المحددة. |
500 خطأ داخلي في الخادم | أرجع الخادم خطأً. راجع رسالة الخطأ لمزيد من التفاصيل. |
503 الخدمة غير متوفرة | قاعدة بيانات Firebase Realtime المحددة غير متاحة مؤقتًا، مما يعني أنه لم تتم محاولة الطلب. |
412 فشل الشرط المسبق | لم تتطابق قيمة ETag المحددة للطلب في رأس if-match مع قيمة الخادم. |
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2024-03-20 (حسب التوقيت العالمي المتفَّق عليه)