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

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

في حال ضبط علامة 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 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'

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

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

البث من واجهة برمجة التطبيقات 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

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

وضع	ستكون البيانات المُشفَّرة بتنسيق 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.