Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

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

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

curl 'https://docs-examples.firebaseio.com/rest/saving-data/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/rest/saving-data/auth-example.json?auth=CREDENTIAL'

طباعة

يؤدي تحديد print=pretty إرجاع البيانات بتنسيق يمكن للبشر قراءته.

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

يؤدي تحديد print=silent إرجاع 204 No Content عند النجاح.

curl 'https://docs-examples.firebaseio.com/rest/saving-data/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/rest/saving-data/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 شائع عن طريق تمرير هذا المفتاح إلى معلمة orderBy . على سبيل المثال ، لاسترداد جميع الديناصورات التي يزيد ارتفاعها عن 3 ، يمكننا القيام بما يلي:

رسوم 20 ب 9141

سيتم فرز أي عقدة لا تحتوي على المفتاح الفرعي الذي نقوم بالترشيح على أساسها بقيمة 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" باستخدام 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'

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

ضع كل شيء معا

يمكننا دمج كل هذه التقنيات لإنشاء استعلامات معقدة. على سبيل المثال ، ربما ترغب في العثور على اسم جميع الديناصورات الأقصر من أو يساوي ارتفاعها من النوع المفضل لدينا ، 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 مع اسم المفتاح orderBy ، سيتم ترتيب البيانات التي تحتوي على المفتاح orderBy المحدد على النحو التالي:

  1. الأطفال الذين لديهم قيمة null للمفتاح الفرعي المحدد يأتون أولاً.
  2. يأتي بعد ذلك الأطفال الذين لديهم قيمة false للمفتاح الفرعي المحدد. إذا كانت قيمة العديد من الأطفال false ، فسيتم فرزها حسب المعجم حسب المفتاح.
  3. يأتي بعد ذلك الأطفال الذين لديهم قيمة true للمفتاح الفرعي المحدد. إذا كان للعديد من الأطفال قيمة true ، فسيتم تصنيفهم حسب المعجم حسب المفتاح.
  4. يأتي الأطفال ذوو القيمة الرقمية بعد ذلك ، ويتم فرزهم بترتيب تصاعدي. إذا كان لدى العديد من الأطفال نفس القيمة العددية للعقدة الفرعية المحددة ، فسيتم فرزهم حسب المفتاح.
  5. تأتي السلاسل بعد الأرقام ، ويتم ترتيبها حسب المعجم بترتيب تصاعدي. إذا كان لدى العديد من الأطفال نفس القيمة للعقدة الفرعية المحددة ، فسيتم ترتيبهم حسب المعجم حسب المفتاح.
  6. تأتي الكائنات أخيرًا ، ويتم ترتيبها حسب المعجم حسب المفتاح بترتيب تصاعدي.
يتم إرجاع النتائج المصفاة بدون ترتيب. إذا كان ترتيب بياناتك مهمًا ، فيجب عليك فرز النتائج في تطبيقك بعد إعادتها من Firebase.

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:

19 د د 616655

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

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

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

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