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

قراءة البيانات مع GET

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

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

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

إضافة معامِلات URI

تقبل واجهة برمجة تطبيقات REST العديد من معاملات الاستعلام عند قراءة البيانات من قاعدة بيانات 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 للعثور على جميع الديناصورات التي تأتي أسماؤها قبل Pterodactyl lexicographically:

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'

استعلامات النطاق مفيدة أيضًا عندما تحتاج إلى ترقيم بياناتك.

ضع كل شيء معا

يمكننا دمج كل هذه الأساليب لإنشاء استعلامات معقدة. على سبيل المثال ، ربما ترغب في العثور على اسم جميع الديناصورات الأقصر من أو يساوي ارتفاعًا من النوع المفضل لدينا ، Stegosaurus:

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. تأتي الكائنات أخيرًا ، ويتم ترتيبها حسب المعجم حسب المفتاح بترتيب تصاعدي.

orderBy = "$ key"

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

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

orderBy = "قيمة بالدولار"

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

orderBy = "الأولوية بالدولار"

عند استخدام معلمة 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

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

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

// 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 APIs.