جارٍ استرداد البيانات

قراءة البيانات باستخدام طلب GET

يمكننا قراءة البيانات من قاعدة بيانات Firebase عن طريق إرسال طلب GET إلى نقطة نهاية عنوان URL الخاصة بها. لنتابع مثال المدوّنة من القسم السابق ونقرأ جميع بيانات مشاركات المدوّنة: 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

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

إضافة مَعلمات URI

تقبل واجهة برمجة تطبيقات REST عدة مَعلمات طلب بحث عند قراءة البيانات من قاعدة بيانات Firebase. في ما يلي المَعلمات الأكثر استخدامًا. للاطّلاع على قائمة كاملة، يُرجى الرجوع إلى مرجع واجهة برمجة تطبيقات REST.

auth

تسمح مَعلمة طلب auth بالوصول إلى البيانات المحمية بموجب Firebase Realtime Database Security Rules، وهي متوافقة مع جميع أنواع الطلبات. يمكن أن تكون الوسيطة سرّ تطبيقك على Firebase أو رمز مصادقة، كما هو موضّح في مقالة المستخدمون في مشاريع Firebase. في المثال التالي، نرسل طلب GET مع مَعلمة auth ، حيث يكون CREDENTIAL إما سرّ تطبيقك على Firebase أو رمز مصادقة: 

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

طباعة

يؤدي تحديد print=pretty إلى عرض البيانات بتنسيق يمكن للمستخدمين قراءته. 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

يؤدي تحديد print=silent إلى عرض 204 No Content عند النجاح. 

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

callback

لإجراء طلبات REST من متصفح ويب على مستوى النطاقات، يمكنك استخدام JSONP لتضمين الاستجابة في دالة رد اتصال JavaScript. أضِف callback= لكي تضمّن واجهة برمجة تطبيقات REST البيانات التي يتم عرضها في الـ دالة رد الاتصال التي تحدّدها. على سبيل المثال: 

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

shallow

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

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

يمكنك تجربة ذلك باستخدام طلب curl هذا: 

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'
لا يمكن استخدام

timeout

استخدِم هذه المَعلمة للحدّ من المدة التي تستغرقها عملية القراءة على جانب الخادم. إذا لم يكتمل طلب القراءة خلال الوقت المخصّص، يتم إنهاؤه مع ظهور خطأ HTTP 400. يكون هذا مفيدًا بشكل خاص عندما تتوقّع نقل بيانات صغيرة ولا تريد الانتظار لفترة طويلة لاسترداد شجرة فرعية كبيرة محتمَلة. قد يختلف وقت القراءة الفعلي استنادًا إلى حجم البيانات والتخزين المؤقت.

حدِّد timeouts باستخدام التنسيق التالي: 3ms، 3s أو 3min، مع رقم ووحدة. إذا لم يتم تحديد ذلك، سيتم تطبيق الحد الأقصى timeout وهو 15min. إذا لم يكن timeout موجبًا أو تجاوز الحد الأقصى، سيتم رفض الطلب مع ظهور خطأ HTTP 400. في المثال التالي، يتضمّن طلب GET قيمة timeout تبلغ 10 ثوانٍ. 

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

فلترة البيانات

يمكننا إنشاء طلبات بحث لفلترة البيانات استنادًا إلى عوامل مختلفة. للبدء، حدِّد كيف تريد فلترة بياناتك باستخدام المَعلمة orderBy. بعد ذلك، ادمِج orderBy مع أي من المَعلمات الخمس الأخرى: limitToFirst وlimitToLast وstartAt وendAt و equalTo.

بما أنّنا جميعًا في Firebase نعتقد أنّ الديناصورات رائعة، سنستخدم مقتطفًا من قاعدة بيانات نموذجية لحقائق عن الديناصورات لتوضيح كيفية فلترة البيانات: 

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

يمكننا فلترة البيانات بإحدى ثلاث طرق: حسب مفتاح العنصر الفرعي أو حسب المفتاح أو حسب القيمة. يبدأ طلب البحث بإحدى هذه المَعلمات، ثم يجب دمجه مع واحدة أو أكثر من المَعلمات التالية: startAt أو endAt أو limitToFirst أو limitToLast أو equalTo.

الفلترة حسب مفتاح عنصر فرعي محدّد

يمكننا فلترة العُقد حسب مفتاح عنصر فرعي شائع عن طريق تمرير هذا المفتاح إلى المَعلمة orderBy. على سبيل المثال، لاسترداد جميع الديناصورات التي يزيد ارتفاعها عن 3، يمكننا إجراء ما يلي: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

سيتم فرز أي عقدة لا تحتوي على مفتاح العنصر الفرعي الذي نفلتره بقيمة null. لمعرفة تفاصيل حول كيفية ترتيب البيانات، يُرجى الاطّلاع على مقالة كيفية ترتيب البيانات.

تتيح Firebase أيضًا طلبات البحث التي يتم ترتيبها حسب العناصر الفرعية المتداخلة بعمق، بدلاً من العناصر الفرعية التي تكون على مستوى واحد فقط. يكون هذا مفيدًا إذا كانت لديك بيانات متداخلة بعمق مثل ما يلي: 

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

للاستعلام عن الارتفاع الآن، نستخدم المسار الكامل للكائن بدلاً من مفتاح واحد: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

لا يمكن لطلبات البحث الفلترة إلا باستخدام مفتاح واحد في كل مرة. يؤدي استخدام المَعلمة orderBy عدة مرات في الطلب نفسه إلى ظهور خطأ.

الفلترة حسب المفتاح

يمكننا أيضًا فلترة العُقد حسب مفاتيحها باستخدام المَعلمة orderBy="$key". يسترد المثال التالي جميع الديناصورات التي يبدأ اسمها بالحرف a إلى m: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

الفلترة حسب القيمة

يمكننا فلترة العُقد حسب قيمة مفاتيح العناصر الفرعية باستخدام المَعلمة orderBy="$value". لنفترض أنّ الديناصورات تشارك في مسابقة رياضية ونحن نتتبّع نتائجها بالتنسيق التالي: 

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

لاسترداد جميع الديناصورات التي حصلت على نتيجة أعلى من 50، يمكننا إرسال الطلب التالي: 

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

يُرجى الاطّلاع على مقالة كيفية ترتيب البيانات للحصول على شرح حول كيفية فرز قيم null والقيم المنطقية والسلاسل والكائنات عند استخدام orderBy="$value".

الفلترة المعقّدة

يمكننا دمج مَعلمات متعددة لإنشاء طلبات بحث أكثر تعقيدًا.

طلبات البحث التي تتضمّن حدًا أقصى

تُستخدم المَعلمتان limitToFirst وlimitToLast لضبط الحد الأقصى لعدد العناصر الفرعية التي نريد تلقّي بياناتها. إذا ضبطنا حدًا أقصى يبلغ 100، لن نتلقّى سوى ما يصل إلى 100 عنصر فرعي مطابق. إذا كان لدينا أقل من 100 رسالة مخزّنة في قاعدة البيانات، سنتلقّى كل عنصر فرعي. ومع ذلك، إذا كان لدينا أكثر من 100 رسالة، لن نتلقّى سوى بيانات 100 من هذه الرسائل. ستكون هذه الرسائل أول 100 رسالة مرتّبة إذا كنا نستخدم limitToFirst أو آخر 100 رسالة مرتّبة إذا كنا نستخدم limitToLast.

باستخدام قاعدة بيانات حقائق الديناصورات وorderBy، يمكننا العثور على أثقل ديناصورين: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

وبالمثل، يمكننا العثور على أقصر ديناصورين باستخدام limitToFirst: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

يمكننا أيضًا إجراء طلبات بحث تتضمّن حدًا أقصى باستخدام orderBy="$value". إذا أردنا إنشاء لوحة صدارة تضم أفضل ثلاثة منافسين في مسابقة الديناصورات الرياضية، يمكننا إجراء ما يلي: 

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

طلبات البحث التي تتضمّن نطاقًا

باستخدام startAt وendAt وequalTo، يمكننا اختيار نقاط بداية ونهاية عشوائية لطلبات البحث. على سبيل المثال، إذا أردنا العثور على جميع الديناصورات التي يبلغ ارتفاعها ثلاثة أمتار على الأقل، يمكننا دمج orderBy وstartAt 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

يمكننا استخدام endAt للعثور على جميع الديناصورات التي تأتي أسماؤها قبل Pterodactyl في الترتيب المعجمي: 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

يمكننا دمج startAt وendAt للحدّ من كلا طرفَي طلب البحث. يجد المثال التالي جميع الديناصورات التي يبدأ اسمها بالحرف "b": 

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

تكون طلبات البحث التي تتضمّن نطاقًا مفيدة أيضًا عندما تحتاج إلى تقسيم بياناتك إلى صفحات.

جارٍ إعداد الردّ

يمكننا دمج كل هذه التقنيات لإنشاء طلبات بحث معقّدة. على سبيل المثال، قد تريد العثور على اسم جميع الديناصورات التي يقل ارتفاعها عن نوعنا المفضّل، وهو Stegosaurus، أو يساويه: 

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

كيفية ترتيب البيانات

يوضّح هذا القسم كيفية ترتيب بياناتك عند استخدام كل من مَعلمات الفلترة الثلاث.

orderBy

عند استخدام orderBy مع اسم مفتاح عنصر فرعي، سيتم ترتيب البيانات التي تحتوي على مفتاح العنصر الفرعي المحدّد على النحو التالي:

  1. تظهر أولاً العناصر الفرعية التي لها قيمة null لمفتاح العنصر الفرعي المحدّد.
  2. تظهر بعد ذلك العناصر الفرعية التي لها قيمة false لمفتاح العنصر الفرعي المحدّد. إذا كان لدى عدة عناصر فرعية قيمة false، يتم فرزها معجميًا حسب المفتاح.
  3. تظهر بعد ذلك العناصر الفرعية التي لها قيمة true لمفتاح العنصر الفرعي المحدّد. إذا كان لدى عدة عناصر فرعية قيمة true، يتم فرزها معجميًا حسب المفتاح.
  4. تظهر بعد ذلك العناصر الفرعية التي لها قيمة رقمية، ويتم فرزها بترتيب تصاعدي. إذا كان لدى عدة عناصر فرعية القيمة الرقمية نفسها لعقدة العنصر الفرعي المحدّدة، يتم فرزها حسب المفتاح.
  5. تأتي السلاسل بعد الأرقام، ويتم فرزها معجميًا بترتيب تصاعدي. إذا كان لدى عدة عناصر فرعية القيمة نفسها لعقدة العنصر الفرعي المحدّدة، يتم ترتيبها معجميًا حسب المفتاح.
  6. تأتي الكائنات أخيرًا، ويتم فرزها معجميًا حسب المفتاح بترتيب تصاعدي.
يتم عرض النتائج المفلترة بدون ترتيب. إذا كان ترتيب بياناتك مهمًا، عليك فرز النتائج في تطبيقك بعد أن يتم عرضها من Firebase.

orderBy="$key"

عند استخدام المَعلمة orderBy="$key" لفرز بياناتك، سيتم عرض البيانات بترتيب تصاعدي حسب المفتاح على النحو التالي. ضَع في اعتبارك أنّه لا يمكن أن تكون المفاتيح إلا سلاسل.

  1. تظهر أولاً العناصر الفرعية التي يمكن تحليل مفتاحها كعدد صحيح 32 بت، ويتم فرزها بترتيب تصاعدي.
  2. تظهر بعد ذلك العناصر الفرعية التي لها قيمة سلسلة كمفتاح، ويتم فرزها معجميًا بترتيب تصاعدي.

orderBy="$value"

عند استخدام المَعلمة orderBy="$value" لفرز بياناتك، سيتم ترتيب العناصر الفرعية حسب قيمتها. تكون معايير الترتيب هي نفسها معايير ترتيب البيانات حسب مفتاح العنصر الفرعي، باستثناء أنّه يتم استخدام قيمة العقدة بدلاً من قيمة مفتاح العنصر الفرعي المحدّد.

orderBy="$priority"

عند استخدام المَعلمة orderBy="$priority" لفرز بياناتك، يتم تحديد ترتيب العناصر الفرعية حسب أولويتها ومفتاحها على النحو التالي. ضَع في اعتبارك أنّه لا يمكن أن تكون قيم الأولوية إلا أرقامًا أو سلاسل.

  1. تظهر أولاً العناصر الفرعية التي ليس لها أولوية (الإعداد التلقائي).
  2. تظهر بعد ذلك العناصر الفرعية التي لها رقم كأولوية. يتم فرزها رقميًا حسب الأولوية، من الأصغر إلى الأكبر.
  3. تظهر أخيرًا العناصر الفرعية التي لها سلسلة كأولوية. يتم فرزها معجميًا حسب الأولوية.
  4. عندما يكون لدى عنصرين فرعيين الأولوية نفسها (بما في ذلك عدم وجود أولوية)، يتم فرزهما حسب المفتاح. تظهر أولاً المفاتيح الرقمية (التي يتم فرزها رقميًا)، تليها المفاتيح المتبقية (التي يتم فرزها معجميًا).

لمزيد من المعلومات عن الأولويات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

البث من واجهة برمجة تطبيقات REST

تتوافق نقاط نهاية Firebase REST مع بروتوكول EventSource / Server-Sent Events، ما يسهّل بث التغييرات إلى موقع واحد في قاعدة بيانات Firebase.

للبدء في البث، علينا إجراء ما يلي:

  1. ضبط عنوان Accept للعميل على text/event-stream
  2. الالتزام بعمليات إعادة توجيه HTTP، وخاصةً رمز حالة HTTP 307
  3. تضمين مَعلمة طلب البحث auth إذا كان موقع قاعدة بيانات Firebase يتطلب إذنًا بالقراءة

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

event: event name
data: JSON encoded data payload

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

put ستكون البيانات بترميز JSON كائنًا يتضمّن مفتاحَين: path وdata
يشير المسار إلى موقع نسبيًا لعنوان URL للطلب
على العميل استبدال جميع البيانات في هذا الموقع في ذاكرته المؤقتة بالبيانات الواردة في الرسالة
patch ستكون البيانات بترميز JSON كائنًا يتضمّن مفتاحَين: path وdata
يشير المسار إلى موقع نسبيًا لعنوان URL للطلب
لكل مفتاح في البيانات، على العميل استبدال المفتاح المقابل في ذاكرته المؤقتة ببيانات هذا المفتاح في الرسالة
keep-alive بيانات هذا الحدث هي null، ولا يلزم اتخاذ أي إجراء
cancel بيانات هذا الحدث هي null
سيتم إرسال هذا الحدث إذا أدّت Firebase Realtime Database Security Rules إلى عدم السماح بالقراءة في الموقع المطلوب
auth_revoked بيانات هذا الحدث هي سلسلة تشير إلى انتهاء صلاحية بيانات الاعتماد
سيتم إرسال هذا الحدث عندما تصبح مَعلمة 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}}

إذا كنت تستخدم Go، يمكنك الاطّلاع على Firego، وهو برنامج تضمين تابع لجهة خارجية حول واجهات برمجة التطبيقات Firebase REST وStreaming.