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

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

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

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

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

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

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

المصادقة

تسمح معلمة طلب 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 على التفاف البيانات المعروضة في التي تحددها. على سبيل المثال:

<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 / الذي يسهّل بث التغييرات إلى مكان واحد في بروتوكول "الأحداث المرسلة من الخادم" قاعدة بيانات Firebase.

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

1. ضبط عنوان "قبول" للعميل على 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.