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

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

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

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

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

إضافة معلمات معرف الموارد المنتظم (URI)

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

المصادقة

تسمح معلمة طلب auth بالوصول إلى البيانات المحمية بواسطة قواعد أمان قاعدة بيانات Firebase في الوقت الفعلي مع جميع أنواع الطلبات. يمكن أن تكون الوسيطة إما سرية تطبيق 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 على التفاف البيانات المعروضة في التي تحددها. على سبيل المثال: 

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

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

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

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

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

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

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

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

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

event: event name
data: JSON encoded data payload

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

وضع ستكون البيانات المرمّزة بتنسيق JSON كائنًا بمفتاحين: المسار والبيانات
يشير المسار إلى موقع مرتبط بعنوان URL الخاص بالطلب
على العميل استبدال جميع البيانات في هذا الموقع في ذاكرة التخزين المؤقت بالبيانات الواردة في الرسالة
رمز تصحيح ستكون البيانات المرمّزة بتنسيق JSON كائنًا بمفتاحين: المسار والبيانات
يشير المسار إلى موقع مرتبط بعنوان URL الخاص بالطلب
بالنسبة إلى كل مفتاح في البيانات، على العميل استبدال المفتاح المقابل في ذاكرة التخزين المؤقت ببيانات هذا المفتاح في الرسالة.
البقاء على قيد الحياة بيانات هذا الحدث فارغة، وليس عليك اتّخاذ أي إجراء.
إلغاء بيانات هذا الحدث فارغة.
سيتم إرسال هذا الحدث إذا تسببت قواعد أمان قاعدة بيانات Firebase في الوقت الفعلي في إيقاف السماح بالقراءة في الموقع المطلوب
تم إلغاء المصادقة بيانات هذا الحدث هي سلسلة تشير إلى انتهاء صلاحية بيانات الاعتماد
سيتم إرسال هذا الحدث عندما تصبح معلَمة المصادقة المقدّمة غير صالحة

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

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