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

قراءة البيانات باستخدام 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'

طباعة

يؤدي تحديد 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'

وقت مستقطع

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

حدِّد السمة timeouts باستخدام أحد التنسيقات التالية: 3ms أو 3s أو 3min، مع رقم ووحدة. في حال عدم تحديد قيمة، سيتم تطبيق الحد الأقصى لـ timeout وهو 15min. إذا لم تكن قيمة timeout موجبة أو تجاوزت الحد الأقصى، سيتم رفض الطلب مع ظهور خطأ HTTP 400. In the following example, the GET request includes a timeout of 10 seconds. 

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'

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

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

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

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. Children with a key that can be parsed as a 32-bit integer come first, sorted in ascending order.
  2. بعد ذلك، يتم ترتيب العناصر الفرعية التي تحتوي على قيمة سلسلة كمفتاح لها، ويتم ترتيبها معجميًا بترتيب تصاعدي.

orderBy="$value"

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

orderBy="$priority"

عند استخدام المَعلمة orderBy="$priority" لترتيب بياناتك، يتم تحديد ترتيب العناصر الفرعية حسب الأولوية والمفتاح على النحو التالي. يُرجى العِلم أنّ قيم الأولوية يمكن أن تكون أرقامًا أو سلاسل فقط.

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

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

البث من REST API

تتوافق نقاط نهاية 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

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

English: put ستكون البيانات المرمّزة بتنسيق JSON عبارة عن عنصر يتضمّن مفتاحَين: المسار والبيانات
يشير المسار إلى موقع جغرافي مرتبط بعنوان URL للطلب
على العميل استبدال جميع البيانات في ذلك الموقع الجغرافي في ذاكرة التخزين المؤقت بالبيانات المقدَّمة في الرسالة
رمز تصحيح ستكون البيانات المرمّزة بتنسيق JSON عبارة عن عنصر يتضمّن مفتاحَين: المسار والبيانات
يشير المسار إلى موقع جغرافي مرتبط بعنوان 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.