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

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

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

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

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

إضافة مَعلمات معرّفات الموارد المنتظمة

تقبل واجهة برمجة التطبيقات REST API العديد من مَعلمات طلب البحث عند قراءة البيانات من قاعدة بيانات 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'

ردّ الاتصال

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

<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'

مهلة

استخدِم هذا الخيار للحد من المدة التي تستغرقها القراءة من جهة الخادم. إذا لم ينته طلب القراءة خلال الوقت المخصّص له، سينتهي بخطأ 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 لحصر طرفَي طلب البحث. يعثر المثال التالي على جميع الديناصورات التي تبدأ أسماؤها بالحرف "ب":

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

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

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

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

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. تظهر العناصر في آخر القائمة، ويتم ترتيبها أبجديًا حسب المفتاح بترتيب تصاعدي.

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

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

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

// 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.