حفظ البيانات

كتابة البيانات باستخدام 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"
    }
  }
}

سيتم الإشارة إلى الطلب الناجح من خلال رمز الحالة 200 OK HTTP، وستحتوي الاستجابة على البيانات المعدَّلة التي تمّت كتابتها في قاعدة البيانات.

تتيح Firebase أيضًا تعديلات على مسارات متعددة. وهذا يعني أنّه يمكن الآن لـ PATCH تعديل القيم في مواقع متعدّدة في قاعدة بيانات Firebase في الوقت نفسه، وهي ميزة فعّالة تساعدك في إزالة التسوية من بياناتك. باستخدام التعديلات المتعددة المسارات، يمكننا إضافة أسماء مستعارة لكل من "آلان" و"غريس" في الوقت نفسه:

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

تعديل البيانات باستخدام الطلبات الشرطية

1. لتنفيذ طلب شرطي في موقع جغرافي، احصل على المعرّف الفريد للبيانات الحالية في هذا الموقع الجغرافي، أو ETag. وإذا تغيّرت البيانات في هذا الموقع الجغرافي، سيتغيّر أيضًا ETag. يمكنك طلب علامة ETag باستخدام أي طريقة أخرى غير PATCH. يستخدم المثال التالي طلب GET.

   curl -i 'https://test.example.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

   يؤدي طلب ETag تحديدًا في العنوان إلى عرض ETag الخاص بالموقع الجغرافي المحدّد في استجابة HTTP.

   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

2. ضمِّن ETag الذي تم إرجاعه في طلبك التالي من النوع PUT أو DELETE لتعديل البيانات التي تتطابق تحديدًا مع قيمة ETag. باتّباع مثالنا، لتعديل العداد إلى 11، أي أكبر بمقدار 1 من القيمة الأولية التي تم جلبها وهي 10، وإخفاق الطلب إذا لم تعُد القيمة مطابقة، استخدِم الرمز التالي:

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

   إذا كانت قيمة البيانات في الموقع المحدّد لا تزال 10، سيتطابق ETag في طلب PUT، وسينجح الطلب، وسيتمّ كتابة 11 في قاعدة البيانات.

   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

   إذا لم يعُد الموقع الجغرافي يتطابق مع ETag، وهو ما قد يحدث إذا كتب مستخدم آخر قيمة جديدة في قاعدة البيانات، سيفشل الطلب بدون الكتابة إلى الموقع الجغرافي. تتضمّن استجابة الإرجاع القيمة الجديدة وETag.

   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

3. استخدِم المعلومات الجديدة إذا قرّرت إعادة محاولة الطلب. لا تعيد Realtime Database محاولة تنفيذ الطلبات الشرطية التي تعذّر تنفيذها تلقائيًا. ومع ذلك، يمكنك استخدام القيمة الجديدة وETag لإنشاء طلب شرطي جديد يتضمّن المعلومات التي تم عرضها في الردّ الذي يشير إلى تعذّر التنفيذ.

تنفّذ الطلبات المشروطة المستندة إلى REST معيار if-match الخاص ببروتوكول HTTP. ومع ذلك، تختلف عن المعيار في ما يلي:

• يمكنك تقديم قيمة ETag واحدة فقط لكل طلب if-match، وليس قيمًا متعدّدة.
• على الرغم من أنّ المعيار يشير إلى ضرورة عرض علامات ETag مع جميع الطلبات، لا تعرض Realtime Database علامات 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" هي قيمة الخادم الوحيدة المسموح بها، وهي الوقت المنقضي منذ بدء حساب الفترة في نظام UNIX، ويُقاس بالملي ثانية.

تحسين أداء الكتابة

إذا كنا نكتب كميات كبيرة من البيانات في قاعدة البيانات، يمكننا استخدام المَعلمة print=silent لتحسين أداء الكتابة وتقليل استخدام النطاق الترددي. في سلوك الكتابة العادي، يستجيب الخادم ببيانات JSON التي تمت كتابتها. عند تحديد print=silent، يغلق الخادم الاتصال فور تلقّي البيانات، ما يقلّل من استخدام النطاق الترددي.

في الحالات التي نرسل فيها العديد من الطلبات إلى قاعدة البيانات، يمكننا إعادة استخدام اتصال HTTPS من خلال إرسال طلب Keep-Alive في عنوان HTTP.

شروط الخطأ

ستعرض واجهة REST API رموز الخطأ في الحالات التالية:

تأمين البيانات

تتضمّن Firebase لغة أمان تتيح لنا تحديد المستخدمين الذين يمكنهم قراءة البيانات وكتابتها في العُقد المختلفة من بياناتنا. يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في Realtime Database Security Rules.