طُرق توفير البيانات |
|
|---|---|
| PUT | كتابة البيانات أو استبدالها في مسار محدّد، مثل fireblog/users/user1/<data> |
| PATCH | تعديل بعض المفاتيح لمسار محدّد بدون استبدال جميع البيانات |
| POST | إضافة إلى قائمة بيانات في قاعدة بيانات Firebase في كل مرة نرسل فيها طلب POST، ينشئ عميل Firebase مفتاحًا فريدًا، مثل fireblog/users/<unique-id>/<data> |
| حذف | إزالة البيانات من مرجع قاعدة بيانات Firebase المحدّد |
كتابة البيانات باستخدام PUT
عملية الكتابة الأساسية من خلال REST API هي PUT. لتوضيح كيفية حفظ البيانات، سننشئ تطبيقًا للتدوين يتضمّن منشورات ومستخدمين. سيتم تخزين جميع بيانات تطبيقنا ضمن مسار `fireblog` على عنوان URL لقاعدة بيانات Firebase `https://docs-examples.firebaseio.com/fireblog`.
لنبدأ بحفظ بعض بيانات المستخدمين في قاعدة بيانات Firebase. سنخزّن كل مستخدم باسم مستخدم فريد، وسنخزّن أيضًا اسمه الكامل وتاريخ ميلاده. بما أنّ كل مستخدم سيكون لديه اسم مستخدم فريد، من المنطقي استخدام PUT هنا بدلاً من POST لأنّ المفتاح متوفّر لدينا ولا نحتاج إلى إنشاء مفتاح جديد.
باستخدام PUT، يمكننا كتابة سلسلة أو رقم أو قيمة منطقية أو مصفوفة أو أي عنصر JSON في
قاعدة بيانات Firebase. في هذه الحالة، سنمرّر له كائنًا:
curl -X PUT -d '{
"alanisawesome": {
"name": "Alan Turing",
"birthday": "June 23, 1912"
}
}' 'https://docs-examples.firebaseio.com/fireblog/users.json'
عند حفظ عنصر JSON في قاعدة البيانات، يتم ربط خصائص العنصر تلقائيًا بالمواقع الجغرافية الفرعية بطريقة متداخلة. إذا انتقلنا إلى العقدة التي تم إنشاؤها حديثًا، فسنرى القيمة "Alan Turing". يمكننا أيضًا حفظ البيانات مباشرةً في موقع فرعي:
curl -X PUT -d '"Alan Turing"' \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/name.json'
curl -X PUT -d '"June 23, 1912"' \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome/birthday.json'
سيؤدي المثالان أعلاه، أي كتابة القيمة في الوقت نفسه كعنصر وكتابتها بشكل منفصل في المواقع الفرعية، إلى حفظ البيانات نفسها في قاعدة بيانات Firebase:
{
"users": {
"alanisawesome": {
"date_of_birth": "June 23, 1912",
"full_name": "Alan Turing"
}
}
}
سيتم الإشارة إلى الطلب الناجح من خلال رمز حالة HTTP 200 OK، وسيحتوي الردّ على البيانات التي كتبناها في قاعدة البيانات. سيؤدي المثال الأول إلى تشغيل حدث واحد فقط على العملاء الذين يشاهدون البيانات، بينما سيؤدي المثال الثاني إلى تشغيل حدثين. تجدر الإشارة إلى أنّه إذا كانت البيانات متوفّرة في مسار المستخدمين، سيؤدي الأسلوب الأول إلى استبدالها، ولكن الطريقة الثانية ستعدّل فقط قيمة كل عقدة فرعية منفصلة مع ترك العقد الفرعية الأخرى بدون تغيير. PUT يعادل
set() في JavaScript SDK.
تعديل البيانات باستخدام PATCH
باستخدام طلب PATCH، يمكننا تعديل بيانات أطفال محدّدين في موقع جغرافي معيّن بدون
استبدال البيانات الحالية. لنضِف لقب "تورينغ" إلى بيانات المستخدم الخاصة به من خلال طلب PATCH:
curl -X PATCH -d '{
"nickname": "Alan The Machine"
}' \
'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'
سيؤدي الطلب أعلاه إلى كتابة nickname في عنصر alanisawesome
بدون حذف العناصر الفرعية name أو birthday. يُرجى العِلم أنّه إذا أصدرنا طلب PUT هنا بدلاً من ذلك، كان سيتم حذف name وbirthday لأنّهما لم يتم تضمينهما في الطلب. البيانات في قاعدة بيانات Firebase
تبدو الآن على النحو التالي:
{
"users": {
"alanisawesome": {
"date_of_birth": "June 23, 1912",
"full_name": "Alan Turing",
"nickname": "Alan The Machine"
}
}
}
سيتم الإشارة إلى الطلب الناجح من خلال رمز حالة HTTP 200 OK، وسيحتوي الرد على البيانات المعدَّلة المكتوبة في قاعدة البيانات.
تتيح Firebase أيضًا التعديلات المتعددة المسارات. يعني ذلك أنّ بإمكان PATCH الآن تعديل القيم في مواقع متعددة في قاعدة بيانات Firebase في الوقت نفسه، وهي ميزة فعّالة تتيح لك
إلغاء تسوية بياناتك. باستخدام التعديلات المتعددة المسارات، يمكننا إضافة أسماء مستعارة لكل من "Alan" و"Grace" في الوقت نفسه:
curl -X PATCH -d '{
"alanisawesome/nickname": "Alan The Machine",
"gracehopper/nickname": "Amazing Grace"
}' \
'https://docs-examples.firebaseio.com/fireblog/users.json'
بعد هذا التعديل، تمت إضافة اللقبَين لكل من "أحمد" و"غادة":
{
"users": {
"alanisawesome": {
"date_of_birth": "June 23, 1912",
"full_name": "Alan Turing",
"nickname": "Alan The Machine"
},
"gracehop": {
"date_of_birth": "December 9, 1906",
"full_name": "Grace Hopper",
"nickname": "Amazing Grace"
}
}
}يُرجى العِلم أنّ محاولة تعديل العناصر من خلال كتابة عناصر تتضمّن المسارات ستؤدي إلى سلوك مختلف. لنلقِ نظرة على ما يحدث إذا حاولنا بدلاً من ذلك تعديل Grace وAlan بهذه الطريقة:
curl -X PATCH -d '{
"alanisawesome": {"nickname": "Alan The Machine"},
"gracehopper": {"nickname": "Amazing Grace"}
}' \
'https://docs-examples.firebaseio.com/fireblog/users.json'
يؤدي ذلك إلى سلوك مختلف، أي استبدال عقدة /fireblog/users بالكامل:
{
"users": {
"alanisawesome": {
"nickname": "Alan The Machine"
},
"gracehop": {
"nickname": "Amazing Grace"
}
}
}تعديل البيانات باستخدام الطلبات الشرطية
يمكنك استخدام الطلبات الشرطية، وهي مكافئ REST للمعاملات، لتعديل البيانات وفقًا لحالتها الحالية. على سبيل المثال، إذا أردت زيادة عدّاد التصويت الإيجابي، وأردت التأكّد من أنّ العدد يعكس بدقة التصويتات الإيجابية المتعدّدة والمتزامنة، استخدِم طلبًا شرطيًا لكتابة القيمة الجديدة في العدّاد. بدلاً من عمليتَي كتابة تغيّران العدّاد إلى الرقم نفسه، يتعذّر تنفيذ أحد طلبَي الكتابة، ويمكنك بعد ذلك إعادة محاولة تنفيذ الطلب باستخدام القيمة الجديدة.- لتنفيذ طلب مشروط في موقع جغرافي معيّن، يجب الحصول على المعرّف الفريد
للبيانات الحالية في ذلك الموقع الجغرافي، أو علامة ETag. وإذا تغيّرت البيانات في ذلك الموقع الجغرافي، يتغيّر أيضًا ETag. يمكنك طلب علامة ETag باستخدام أي طريقة أخرى غير
PATCH. يستخدم المثال التالي طلبGET. يؤدي استدعاء ETag تحديدًا في العنوان إلى عرض ETag للموقع الجغرافي المحدّد في استجابة HTTP.curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
HTTP/1.1 200 OK Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * ETag: [ETAG_VALUE] Cache-Control: no-cache 10 // Current value of the data at the specified location
- أدرِج علامة ETag التي تم عرضها في طلب
PUTأوDELETEالتالي لتعديل البيانات التي تتطابق تحديدًا مع قيمة علامة ETag هذه. باتّباع المثال السابق، لتعديل العدّاد إلى 11، أو إلى قيمة أكبر من القيمة الأولية التي تم جلبها وهي 10، وإلغاء الطلب إذا لم تعد القيمة مطابقة، استخدِم الرمز التالي: إذا كانت قيمة البيانات في الموقع المحدّد لا تزال 10، يتطابق ETag في طلبcurl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match:[ETAG_VALUE]'
PUT، وينجح الطلب، وتتم كتابة 11 في قاعدة البيانات. إذا لم يعُد الموقع الجغرافي يتطابق مع علامة ETag، وهو ما قد يحدث إذا كتب مستخدم آخر قيمة جديدة في قاعدة البيانات، سيتعذّر تنفيذ الطلب بدون الكتابة في الموقع الجغرافي. يتضمّن الردّ القيمة الجديدة وعلامة ETag.HTTP/1.1 200 OK Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * Cache-Control: no-cache 11 // New value of the data at the specified location, written by the conditional request
HTTP/1.1 412 Precondition Failed Content-Length: 6 Content-Type: application/json; charset=utf-8 Access-Control-Allow-Origin: * ETag: [ETAG_VALUE] Cache-Control: no-cache 12 // New value of the data at the specified location
- استخدِم المعلومات الجديدة إذا قرّرت إعادة محاولة إرسال الطلب. لا تعيد Realtime Database تلقائيًا محاولة تنفيذ الطلبات المشروطة التي تعذّر تنفيذها. ومع ذلك، يمكنك استخدام القيمة الجديدة وETag لإنشاء طلب شرطي جديد باستخدام المعلومات التي تم عرضها من خلال استجابة الفشل.
تنفّذ الطلبات المشروطة المستندة إلى REST معيار HTTP if-match. ومع ذلك، فإنها تختلف عن المعيار بالطرق التالية:
- يمكنك تقديم قيمة ETag واحدة فقط لكل طلب if-match، وليس قيمًا متعددة.
- على الرغم من أنّ المعيار يقترح عرض علامات ETag مع جميع الطلبات،
لا تعرض قاعدة بيانات الوقت الفعلي علامات ETag إلا مع الطلبات التي تتضمّن العنوان
X-Firebase-ETag. ويؤدي ذلك إلى تقليل التكلفة الواردة في الفاتورة للطلبات العادية.
قد تكون الطلبات المشروطة أيضًا أبطأ من طلبات REST العادية.
حفظ قوائم البيانات
لإنشاء مفتاح فريد يستند إلى الطابع الزمني لكل عنصر فرعي تتم إضافته إلى مرجع قاعدة بيانات Firebase،
يمكننا إرسال طلب POST. بالنسبة إلى مسار users، من المنطقي
تحديد مفاتيحنا الخاصة لأنّ كل مستخدم لديه اسم مستخدم فريد. ولكن عندما يضيف المستخدمون منشورات مدوّنة إلى التطبيق، سنستخدم طلب POST لإنشاء مفتاح تلقائيًا لكل منشور مدوّنة:
curl -X POST -d '{
"author": "alanisawesome",
"title": "The Turing Machine"
}' 'https://docs-examples.firebaseio.com/fireblog/posts.json'
يحتوي مسار posts الآن على البيانات التالية:
{
"posts": {
"-JSOpn9ZC54A4P4RoqVa": {
"author": "alanisawesome",
"title": "The Turing Machine"
}
}
}
يُرجى ملاحظة أنّه تم إنشاء المفتاح -JSOpn9ZC54A4P4RoqVa تلقائيًا لأنّنا استخدمنا طلب POST. ستتم الإشارة إلى الطلب الناجح من خلال رمز حالة HTTP 200 OK، وستتضمّن الاستجابة مفتاح البيانات الجديدة التي تمت إضافتها:
{"name":"-JSOpn9ZC54A4P4RoqVa"}جارٍ إزالة البيانات
لإزالة البيانات من قاعدة البيانات، يمكننا إرسال طلب DELETE مع عنوان URL للمسار الذي نريد حذف البيانات منه. سيؤدي ما يلي إلى حذف Alan من مسار
users:
curl -X DELETE \ 'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'
ستتم الإشارة إلى طلب DELETE الناجح من خلال رمز حالة HTTP 200 OK مع استجابة تحتوي على JSON null.
مَعلمات معرّف الموارد المنتظم (URI)
تقبل واجهة برمجة التطبيقات REST API معلمات معرّف الموارد المنتظم (URI) التالية عند كتابة البيانات في قاعدة البيانات:
auth
تسمح مَعلمة الطلب auth بالوصول إلى البيانات المحمية من خلال Firebase Realtime Database Security Rules، وهي متوافقة مع جميع أنواع الطلبات. يمكن أن تكون الوسيطة إما مفتاح تطبيق Firebase السري أو رمز مصادقة، وسنتناول ذلك في قسم تفويض المستخدم. في المثال التالي، نرسل طلب POST مع مَعلمة auth، حيث تكون CREDENTIAL إما مفتاح تطبيق Firebase السري أو رمز مصادقة مميزًا:
curl -X POST -d '{"Authenticated POST request"}' \
'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'
طباعة
تتيح لنا مَعلمة print تحديد تنسيق الاستجابة من قاعدة البيانات. ستؤدي إضافة print=pretty إلى طلبنا إلى عرض البيانات بتنسيق يمكن لشخص عادي قراءته. يتم دعم print=pretty من خلال طلبات GET وPUT وPOST وPATCH وDELETE.
لمنع ظهور الناتج من الخادم عند كتابة البيانات، يمكننا إضافة print=silent إلى طلبنا. ستكون الاستجابة الناتجة فارغة ويُشار إليها برمز حالة HTTP 204 No Content إذا كان الطلب ناجحًا.
يتوافق print=silent مع طلبات GET وPUT وPOST وPATCH.
كتابة قيم الخادم
يمكن كتابة قيم الخادم في موقع جغرافي باستخدام قيمة عنصر نائب، وهي عنصر يحتوي على مفتاح ".sv" واحد. قيمة هذا المفتاح هي نوع قيمة الخادم التي نريد ضبطها.
على سبيل المثال، لضبط طابع زمني عند إنشاء مستخدم، يمكننا إجراء ما يلي:
curl -X PUT -d '{".sv": "timestamp"}' \
'https://docs-examples.firebaseio.com/alanisawesome/createdAt.json'
"timestamp" هي قيمة الخادم الوحيدة المتوافقة، وهي الوقت المنقضي منذ بدء حقبة يونكس بالملي ثانية.
تحسين أداء الكتابة
إذا كنا نكتب كميات كبيرة من البيانات في قاعدة البيانات، يمكننا استخدام المَعلمة print=silent لتحسين أداء الكتابة وتقليل استخدام معدل نقل البيانات. في سلوك الكتابة العادي، يستجيب الخادم ببيانات JSON التي تمت كتابتها.
عند تحديد print=silent، يغلق الخادم الاتصال فورًا بعد تلقّي البيانات، ما يقلّل من استخدام معدل نقل البيانات.
في الحالات التي نرسل فيها طلبات كثيرة إلى قاعدة البيانات، يمكننا إعادة استخدام اتصال HTTPS
من خلال إرسال طلب Keep-Alive في عنوان HTTP.
حالات الخطأ
ستعرض واجهة برمجة التطبيقات REST رموز خطأ في الحالات التالية:
| رموز حالة HTTP | |
|---|---|
| 400 طلب غير صالح |
إحدى حالات الخطأ التالية:
|
| 401 غير مصرّح به |
إحدى حالات الخطأ التالية:
|
| 404 لم يتم العثور على الصفحة | لم يتم العثور على قاعدة بيانات Firebase المحدّدة. |
| 500 خطأ في الخادم الداخلي | عرَض الخادم خطأً. يُرجى الاطّلاع على رسالة الخطأ لمزيد من التفاصيل. |
| 503 الخدمة غير متاحة | قاعدة بيانات Firebase في الوقت الفعلي المحدّدة غير متاحة مؤقتًا، ما يعني أنّه لم تتم محاولة تنفيذ الطلب. |
تأمين البيانات
يوفّر Firebase لغة أمان تتيح لنا تحديد المستخدمين الذين لديهم إذن بالوصول للقراءة والكتابة إلى عُقد مختلفة من بياناتنا. يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في Realtime Database Security Rules.
بعد أن تناولنا كيفية حفظ البيانات، يمكننا التعرّف على كيفية استرداد بياناتنا من قاعدة بيانات Firebase من خلال REST API في القسم التالي.