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

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

ردّ الاتصال

لإجراء طلبات 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=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 مع أيّ من مَعلمات طلب البحث "فلترة البيانات".

مهلة

استخدِم هذا الخيار للحد من المدة التي تستغرقها القراءة من جهة الخادم. إذا لم ينته طلب القراءة خلال الوقت المحدّد، سينتهي بخطأ 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.

عرض البيانات التي تمت فلترتها بدون ترتيب: عند استخدام واجهة برمجة تطبيقات REST، يتم عرض النتائج التي تمت فلترتها بترتيب غير محدّد لأنّ برامج ترجمة 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 للعثور على جميع الديناصورات التي وردت أسماؤها قبل "تيروداكتيل" حسب المعنى:

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

startAt وendAt شاملان، ما يعني أنّ "pterodactyl" سيطابق الطلب أعلاه.

يمكننا الجمع بين 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 نتائج غير مرتبة: لا تفرض مفسّرات 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. عندما يكون لعنصرَين الأولوية نفسها (بما في ذلك عدم تحديد أي أولوية)، يتم ترتيبهما حسب المفتاح. تأتي المفاتيح الرقمية أولاً (مُصنَّفة رقميًا)، تليها المفاتيح المتبقية (مُصنَّفة alfabetically).

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

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

تتوافق نقاط نهاية Firebase REST مع بروتوكول EventSource / الأحداث المُرسَلة من الخادم، ما يسهِّل بث التغييرات إلى مكان واحد في قاعدة بيانات Firebase.

لبدء البث، سنحتاج إلى تنفيذ ما يلي:

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

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

event: event name
data: JSON encoded data payload

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

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