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

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

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

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

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

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

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

auth

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

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

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

طباعة

يؤدي تحديد 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 API البيانات التي يتم عرضها في دالة رد الاتصال التي تحدّدها. على سبيل المثال:

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

سطحي

هذه ميزة متقدّمة مصمَّمة لمساعدتك في العمل على مجموعات بيانات كبيرة بدون الحاجة إلى تنزيل كل شيء. لاستخدامها، أضِف 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'

لا يمكن استخدام

shallow مع أيّ من مَعلمات طلب البحث "تصفية البيانات".

مهلة

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

حدِّد 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.

يتم عرض البيانات المفلتَرة بدون ترتيب: عند استخدام REST API، يتم عرض النتائج المفلتَرة بترتيب غير محدّد لأنّ برامج تحليل JSON لا تفرض أي ترتيب. إذا كان ترتيب بياناتك مهمًا، عليك ترتيب النتائج في تطبيقك بعد أن يتم إرجاعها من Firebase.

بما أنّنا جميعًا في 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 عدة مرات في الطلب نفسه إلى حدوث خطأ.

إضافة الفهرسة إلى Firebase Realtime Database Security Rules: إذا كنت تستخدم orderBy في تطبيقك، عليك تحديد المفاتيح التي ستتم فهرستها من خلال قاعدة .indexOn في Firebase Realtime Database Security Rules. اطّلِع على المستندات حول قاعدة .indexOn للحصول على مزيد من المعلومات.

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

يمكننا أيضًا فلترة العُقد حسب مفاتيحها باستخدام المَعلمة 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".

إضافة الفهرسة إلى Firebase Realtime Database Security Rules: إذا كنت تستخدم orderBy="$value" في تطبيقك، عليك إضافة .value إلى القواعد في الفهرس المناسب. اطّلِع على المستندات حول قاعدة .indexOn للحصول على مزيد من المعلومات.

التصفية المعقّدة

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

طلبات البحث المحدودة

يتم استخدام المَعلمتَين 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 شاملان، ما يعني أنّ البحث عن "تيروداكتيل" سيؤدي إلى ظهور نتائج مطابقة لطلب البحث أعلاه.

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

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

الحرف \uf8ff المستخدَم في طلب البحث أعلاه هو نقطة رمزية عالية جدًا في نطاق Unicode. بما أنّ هذا الرمز يأتي بعد معظم الأحرف العادية في Unicode، يتطابق طلب البحث مع جميع القيم التي تبدأ بالحرف b.

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

خلاصة ما سبق ذكره

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

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"

كيف يتم ترتيب البيانات؟

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

تعرض واجهة REST API نتائج غير مرتبة: لا تفرض برامج تحليل JSON أي ترتيب على مجموعة النتائج. على الرغم من أنّه يمكن استخدام orderBy مع startAt أو endAt أو limitToFirst أو limitToLast لعرض مجموعة فرعية من البيانات، لن يتم ترتيب النتائج المعروضة. لذلك، قد يكون من الضروري ترتيب النتائج يدويًا إذا كان الترتيب مهمًا.

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" لترتيب بياناتك، يتم تحديد ترتيب العناصر الفرعية حسب أولويتها ومفتاحها على النحو التالي. يُرجى العِلم أنّ قيم الأولوية يمكن أن تكون أرقامًا أو سلاسل فقط.

يتم تخزين الأولويات الرقمية وترتيبها كأرقام فاصلة عائمة مزدوجة الدقة وفقًا لمعيار IEEE 754. يتم دائمًا تخزين المفاتيح كسلاسل ويتم التعامل معها كأرقام فقط عندما يمكن تحليلها كعدد صحيح 32 بت.

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

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

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

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

لبدء البث، علينا تنفيذ ما يلي:

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

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

event: event name
data: JSON encoded data payload

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

وضع	ستكون البيانات المرمّزة بتنسيق JSON عبارة عن عنصر يتضمّن مفتاحَين: path وdata يشير المسار إلى موقع نسبي إلى عنوان URL للطلب على العميل استبدال جميع البيانات في ذلك الموقع في ذاكرة التخزين المؤقت بالبيانات الواردة في الرسالة
رمز تصحيح	ستكون البيانات المرمّزة بتنسيق JSON عبارة عن عنصر يتضمّن مفتاحَين: path وdata يشير المسار إلى موقع نسبي لعنوان URL للطلب بالنسبة إلى كل مفتاح في البيانات، على العميل استبدال المفتاح المقابل في ذاكرة التخزين المؤقت بالبيانات الخاصة بهذا المفتاح في الرسالة
keep-alive	البيانات الخاصة بهذا الحدث فارغة، ولا يلزم اتّخاذ أي إجراء
إلغاء	بيانات هذا الحدث فارغة سيتم إرسال هذا الحدث إذا لم يعُد مسموحًا Firebase Realtime Database Security Rules بقراءة الموقع الجغرافي المطلوب
auth_revoked	بيانات هذا الحدث هي سلسلة نصية تشير إلى أنّ بيانات الاعتماد قد انتهت صلاحيتها سيتم إرسال هذا الحدث عندما تصبح مَعلمة المصادقة المقدَّمة غير صالحة.

في ما يلي مثال على مجموعة من الأحداث التي قد يرسلها الخادم:

// 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، وهو برنامج تضمين تابع لجهة خارجية يتيح استخدام واجهات برمجة التطبيقات REST وStreaming في Firebase.