استرجاع البيانات

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

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

  1. الأطفال الذين لديهم مفتاح يمكن تحليله كعدد صحيح 32 بت يأتي أولاً، ويتم فرزهم بترتيب تصاعدي.
  2. يأتي بعد ذلك الأطفال الذين لديهم قيمة سلسلة كمفتاح، ويتم فرزهم بشكل معجمي بترتيب تصاعدي.

ترتيب حسب = "قيمة $"

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

ترتيب حسب = "$ الأولوية"

عند استخدام المعلمة orderBy="$priority" لفرز بياناتك، يتم تحديد ترتيب الأطفال حسب أولويتهم ومفتاحهم على النحو التالي. ضع في اعتبارك أن قيم الأولوية يمكن أن تكون أرقامًا أو سلاسل فقط.

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

لمزيد من المعلومات حول الأولويات، راجع مرجع API .

البث من REST API

تدعم نقاط نهاية Firebase REST بروتوكول EventSource / Server-Sent Events ، مما يجعل من السهل دفق التغييرات إلى موقع واحد في قاعدة بيانات 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 Realtime في عدم السماح بالقراءة في الموقع المطلوب
auth_revoced بيانات هذا الحدث عبارة عن سلسلة تشير إلى انتهاء صلاحية بيانات الاعتماد
سيتم إرسال هذا الحدث عندما تصبح معلمة المصادقة المقدمة غير صالحة

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

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