تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

حفظ البيانات

طرق حفظ البيانات
وضع	كتابة البيانات أو استبدالها في مسار محدّد، مثل `fireblog/users/user1/<data>`
رمز التصحيح	تحديث بعض المفاتيح لمسار محدد دون استبدال جميع البيانات.
طريقة POST	يمكنك الإضافة إلى قائمة بيانات في قاعدة بيانات Firebase. في كل مرة نرسل فيها طلب `POST`، يُنشئ عميل Firebase مفتاحًا فريدًا، مثل `fireblog/users/<unique-id>/<data>`.
حذف	إزالة البيانات من مرجع قاعدة بيانات Firebase المحدّد

يُرجى العِلم أنّ جميع الأمثلة تستخدم Firebase Realtime Database وdocs-example.firebaseio.com للقراءة فقط. يمكنك استبدال عنوان URL الخاص بـ Realtime Database بعنوان URL من وحدة تحكّم Firebase التي يمكنك الوصول إليها.

كتابة البيانات باستخدام PUT

عملية الكتابة الأساسية من خلال واجهة برمجة تطبيقات REST هي 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، استجابة سيحتوي على البيانات التي كتبناها إلى قاعدة البيانات. المثال الأول سوف إلى تشغيل حدث واحد على العملاء الذين يشاهدون البيانات، بينما سيؤدي المثال الثاني إلى تشغيل 2. من المهم ملاحظة أنه إذا كانت البيانات موجودة بالفعل في مسار المستخدمين، فإن الطريقة الأولى ستستبدلها، لكن الطريقة الثانية ستعدّل فقط قيمة كل عنصر ثانوي منفصل العقدة مع ترك العناصر الثانوية الأخرى بدون تغيير. PUT تساوي set() في حزمة تطوير البرامج (SDK) لJavaScript.

تحديث البيانات باستخدام التصحيح

باستخدام طلب 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 في الوقت نفسه، وهي ميزة فعّالة تتيح لك. إلغاء تطبيع بياناتك باستخدام التحديثات متعددة المسارات، يمكننا إضافة ألقاب لكل من آلان وغريس في الوقت نفسه:

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.
```
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
```
تضمين علامة 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
```
استخدِم المعلومات الجديدة إذا قرّرت إعادة محاولة تقديم الطلب. Realtime Database لا يعيد تلقائيًا محاولة تنفيذ الطلبات الشرطية التي تعذّر تنفيذها. ومع ذلك، يمكنك استخدام القيمة الجديدة وETag لإنشاء طلب مشروط جديد باستخدام المعلومات التي قامت بإرجاعها استجابة الفشل.

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

يمكنك تقديم قيمة ETag واحدة فقط لكل طلب إذا كانت المطابقة، وليس عدة طلبات.
وفي حين أن المعيار يقترح إرجاع علامات ETag مع جميع الطلبات، لا تعرض قاعدة البيانات في الوقت الفعلي سوى ETags مع الطلبات التي تتضمن عنوان 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. سيتم الإشارة إلى الطلب الناجح من خلال 200 OK. رمز حالة HTTP، وستحتوي الاستجابة على مفتاح البيانات الجديدة التي تمت إضافتها:

{"name":"-JSOpn9ZC54A4P4RoqVa"}

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

لإزالة بيانات من قاعدة البيانات، يمكننا إرسال طلب DELETE يحتوي على عنوان URL للمسار الذي تريد حذف البيانات منه. سيؤدي ما يلي إلى حذف سمير من مسار users:

curl -X DELETE \
  'https://docs-examples.firebaseio.com/fireblog/users/alanisawesome.json'

ستتم الإشارة إلى طلب DELETE الناجح برمز حالة HTTP 200 OK مع استجابة تحتوي على JSON null.

معلمات معرف الموارد المنتظم (URI)

تقبل واجهة برمجة تطبيقات REST معلمات URI التالية عند كتابة البيانات في قاعدة البيانات:

المصادقة

تسمح معلمة طلب 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'

في حال ضبط علامة debug للرمز المميّز، يمكن العثور على معلومات تصحيح الأخطاء في عنوان X-Firebase-Auth-Debug للاستجابة.

طباعة

تتيح لنا معلمة 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 رموز الخطأ في ظل الظروف التالية:

رموز حالة 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 لم يتم العثور على الصفحة	لم يتم العثور على قاعدة بيانات Firebase المحدّدة.
500 خطأ في الخادم الداخلي	عرَض الخادم خطأ. يمكنك الاطّلاع على رسالة الخطأ للحصول على مزيد من التفاصيل.
503 الخدمة غير متاحة	قاعدة بيانات Firebase في الوقت الفعلي المحددة غير متاحة مؤقتًا، مما يعني أن قاعدة بيانات لم تتم محاولة تنفيذ الطلب.

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

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

والآن بعد أن تناولنا حفظ البيانات، يمكننا معرفة كيفية استرداد البيانات من Firebase قاعدة البيانات من خلال واجهة برمجة تطبيقات REST في القسم التالي.

حفظ البيانات

طرق حفظ البيانات

كتابة البيانات باستخدام PUT

تحديث البيانات باستخدام التصحيح

تحديث البيانات باستخدام الطلبات المشروطة

حفظ قوائم البيانات

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

معلمات معرف الموارد المنتظم (URI)

المصادقة

طباعة

كتابة قيم الخادم

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

حالات الخطأ

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