يتناول هذا المستند أساسيات استرداد البيانات وكيفية الترتيب والتصفية بيانات Firebase.
قبل البدء
تأكَّد من إعداد تطبيقك وإمكانية الوصول إلى قاعدة البيانات على النحو الموضّح في
دليل Get Started
.
جارٍ استرداد البيانات
يتم استرداد بيانات Firebase إما من خلال استدعاء لمرة واحدة إلى GetValue()
أو
إرفاقها بـ ValueListener
في مرجع FirebaseDatabase
. القيمة
يتم استدعاء المستمع مرة واحدة للحالة الأولية للبيانات ومرة أخرى في أي وقت
التغييرات في البيانات.
الحصول على DatabaseReference
لكتابة بيانات إلى قاعدة البيانات، أنت بحاجة إلى نسخة افتراضية من DatabaseReference
:
// Get the root reference location of the database. firebase::database::DatabaseReference dbref = database->GetReference();
قراءة البيانات مرة واحدة
ويمكنك استخدام الطريقة GetValue()
لقراءة نبذة ثابتة عن
والمحتوى في مسار معين مرة واحدة. ستتضمّن نتيجة المهمة لقطة
الذي يتضمن جميع البيانات في هذا الموقع، بما في ذلك البيانات الفرعية. إذا لم تكن هناك بيانات،
اللقطة التي يتم عرضها هي null
.
firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("Leaders").GetValue();
عند تقديم الطلب، علينا الانتظار إلى أن كاملة قبل أن نتمكن من قراءة القيمة. نظرًا لأن الألعاب تعمل عادةً بشكل متكرر، تعتمد على معاودة الاتصال بشكل أقل من التطبيقات الأخرى، فستقوم عادةً باستطلاع إتمام المشروع.
// In the game loop that polls for the result... if (result.status() != firebase::kFutureStatusPending) { if (result.status() != firebase::kFutureStatusComplete) { LogMessage("ERROR: GetValue() returned an invalid result."); // Handle the error... } else if (result.error() != firebase::database::kErrorNone) { LogMessage("ERROR: GetValue() returned error %d: %s", result.error(), result.error_message()); // Handle the error... } else { firebase::database::DataSnapshot snapshot = result.result(); // Do something with the snapshot... } }
تظهر هنا بعض عمليات التحقق الأساسية من الأخطاء، راجع firebase::المستقبل ومعلومات حول التحقق من الأخطاء وطرق تحديد متى تكون النتيجة جاهزة.
الاستماع إلى الأحداث
يمكنك إضافة مستمعين للاشتراك في التغييرات التي تطرأ على البيانات:
فئة أساسية واحدة (ValueListener
)
رد الاتصال | معدّل الاستخدام |
---|---|
OnValueChanged |
قراءة التغييرات التي تتم على محتوى المسار بالكامل والاستماع إليها |
فئة أساسية واحدة (OnChildListener
)
OnChildAdded
| استرداد قوائم العناصر أو الاستماع إلى الإضافات إلى قائمة من العناصر.
الاستخدام المقترَح مع OnChildChanged و
OnChildRemoved لمراقبة التغييرات في القوائم. |
OnChildChanged |
رصد التغييرات على العناصر في القائمة الاستخدام مع
OnChildAdded وOnChildRemoved للمراقبة
التغييرات على القوائم. |
OnChildRemoved |
رصد العناصر التي تتم إزالتها من القائمة الاستخدام مع
OnChildAdded وOnChildChanged للمراقبة
التغييرات على القوائم. |
OnChildMoved |
الاستماع إلى التغييرات التي تطرأ على ترتيب العناصر في قائمة مع ترتيب
تتّبع OnChildMoved استدعاءات دائمًا
OnChildChanged طلبات معاودة الاتصال بسبب طلب العنصر
تغيير (استنادًا إلى طريقة الترتيب الحالية). |
فئة ValueListener
يمكنك استخدام استدعاءات OnValueChanged
للاشتراك في التغييرات التي تطرأ على
والمحتوى في مسار معين. يتم تشغيل معاودة الاتصال هذه مرة واحدة عندما يكون المستمع
ومرة أخرى في كل مرة تتغير فيها البيانات، بما في ذلك الأطفال. تشير رسالة الأشكال البيانية
يتم تمرير نبذة عن معاودة الاتصال تحتوي على جميع البيانات في هذا الموقع، بما في ذلك
البيانات الفرعية. إذا لم تتوفّر بيانات، ستكون النبذة التي يتم عرضها هي null
.
يوضح المثال التالي لعبة تسترد نتائج لوحة صدارة من قاعدة البيانات:
class LeadersValueListener : public firebase::database::ValueListener { public: void OnValueChanged( const firebase::database::DataSnapshot& snapshot) override { // Do something with the data in snapshot... } void OnCancelled(const firebase::database::Error& error_code, const char* error_message) override { LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code, error_message); } }; // Elsewhere in the code... LeadersValueListener* listener = new LeadersValueListener(); firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("Leaders").AddValueListener(listener);
تحتوي نتيجة Future<DataSnapshot>
على البيانات المتوفّرة في الموقع الجغرافي المحدّد.
في قاعدة البيانات وقت الحدث. جارٍ الاتصال بالرقم value()
من أجل الحصول على نبذة
يكون ناتجها Variant
التي تمثل البيانات.
في هذا المثال، يتم أيضًا إلغاء طريقة OnCancelled
لمعرفة ما إذا كانت قراءة
تم إلغاؤه. على سبيل المثال، يمكن إلغاء القراءة إذا لم يكن لدى العميل
إذن للقراءة من موقع قاعدة بيانات Firebase. الإجراء الذي سينفّذه database::Error
هو
للإشارة إلى سبب حدوث الفشل.
حصة ChildListener
يتم تشغيل الأحداث الفرعية استجابةً لعمليات محددة تحدث في
العناصر الثانوية لعقدة من أي عملية، مثل إضافة عنصر ثانوي جديد من خلال
طريقة PushChild()
أو بيانات فرعية يتم تعديلها من خلال UpdateChildren()
. ويمكن أن تكون كلٌّ من هذه الأدوات معًا مفيدة للاستماع إلى التغييرات في
عقدة معينة في قاعدة بيانات. على سبيل المثال، قد تستخدم إحدى الألعاب هذه الطرق
معًا لمراقبة النشاط في التعليقات على جلسة اللعبة، كما هو موضّح أدناه:
class SessionCommentsChildListener : public firebase::database::ChildListener { public: void OnChildAdded(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnChildChanged(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnChildRemoved( const firebase::database::DataSnapshot& snapshot) override { // Do something with the data in snapshot ... } void OnChildMoved(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnCancelled(const firebase::database::Error& error_code, const char* error_message) override { LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s", error_code, error_message); } }; // elsewhere .... SessionCommentsChildListener* listener = new SessionCommentsChildListener(); firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("GameSessionComments").AddChildListener(listener);
يتم عادةً استخدام استدعاء OnChildAdded
لاسترداد قائمة
العناصر في قاعدة بيانات Firebase. يتم استدعاء دالة معاودة الاتصال OnChildAdded
مرة واحدة
لكل طفل حالي ثم مرة أخرى في كل مرة تتم فيها إضافة طفل جديد إلى
المسار المحدد. يتم السماح للمستمِع بأخذ لقطة تحتوي على الطفل الجديد
البيانات.
ويتم استدعاء دالة الاستدعاء OnChildChanged
في أي وقت يتم فيه تعديل عقدة فرعية.
يتضمن ذلك أي تعديلات على العناصر التابعة للعقدة الفرعية. من المهم
يتم استخدامه عادةً مع OnChildAdded
وOnChildRemoved
.
للرد على التغييرات في قائمة من العناصر. تم تمرير اللقطة إلى
يحتوي المستمع على البيانات المحدثة للطفل.
يتم تفعيل معاودة الاتصال OnChildRemoved
عند إزالة عنصر ثانوي فوري.
ويتم استخدامها عادةً مع OnChildAdded
و
OnChildChanged
طلبات معاودة الاتصال. تحتوي اللقطة التي يتم تمريرها إلى معاودة الاتصال على
بيانات العنصر الثانوي الذي تمت إزالته.
يتم تشغيل استدعاء OnChildMoved
عند استخدام OnChildChanged
عن طريق تحديث يؤدي إلى إعادة ترتيب الطفل. من المهم
مع البيانات المطلوبة باستخدام OrderByChild
أو OrderByValue
.
فرز البيانات وتصفيتها
يمكنك استخدام الفئة Query
التي تتضمّن Realtime Database لاسترداد بيانات مرتّبة حسب.
مفتاح أو حسب القيمة أو حسب القيمة التابعة لفرد. يمكنك أيضًا فلترة
النتيجة التي تم فرزها إلى عدد محدد من النتائج أو مجموعة من المفاتيح أو
القيم.
فرز البيانات
لاسترداد البيانات التي تم فرزها، ابدأ بتحديد إحدى طرق الترتيب حسب لتحديد كيفية ترتيب النتائج:
الطريقة | الاستخدام |
---|---|
OrderByChild() |
يمكنك ترتيب النتائج حسب قيمة مفتاح فرعي محدّد. |
OrderByKey()
| يمكنك ترتيب النتائج حسب المفاتيح الثانوية. |
OrderByValue() |
ترتيب النتائج حسب القيم الثانوية |
يمكنك استخدام طريقة واحدة فقط لكل طلب على حدة في كل مرة. استدعاء طريقة الطلب حسب عدة مرات في نفس الاستعلام يؤدي إلى حدوث خطأ.
يوضح المثال التالي كيفية الاشتراك في نتيجة. قائمة الصدارة مرتبة حسب النتيجة
firebase::database::Query query = dbRef.GetReference("Leaders").OrderByChild("score"); // To get the resulting DataSnapshot either use query.GetValue() and poll the // future, or use query.AddValueListener() and register to handle the // OnValueChanged callback.
تحدّد هذه السمة firebase::Query
الذي يمكن دمجه مع
يزامن ValueListener البرنامج مع ليدربورد
في قاعدة البيانات، مرتبة حسب درجة كل إدخال.
يمكنك قراءة المزيد حول هيكلة بياناتك بكفاءة في
تنظيم قاعدة البيانات.
يحدد استدعاء طريقة OrderByChild()
المفتاح الفرعي لترتيب
النتائج حسب. في هذه الحالة، يتم ترتيب النتائج حسب قيمة "score"
قيمة في كل فرع. لمزيد من المعلومات حول كيفية ترتيب أنواع البيانات الأخرى،
راجِع كيفية ترتيب بيانات طلبات البحث.
تصفية البيانات
لتصفية البيانات، يمكنك دمج أي من طرق الحد أو النطاق مع الترتيب حسب عند إنشاء استعلام.
الطريقة | الاستخدام |
---|---|
LimitToFirst() |
لتعيين الحد الأقصى لعدد العناصر المراد عرضها من بداية قائمة نتائج مرتبة. |
LimitToLast() |
لضبط الحد الأقصى لعدد السلع المطلوب عرضها من نهاية طلب الشراء قائمة بالنتائج. |
StartAt() |
عرض عناصر أكبر من أو تساوي المفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
EndAt() |
إرجاع عناصر أقل من أو تساوي المفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
EqualTo() |
إرجاع عناصر مساوية للمفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
على عكس طرق الترتيب حسب، يمكنك الجمع بين دوال متعددة للحدود أو النطاقات.
على سبيل المثال، يمكنك الجمع بين الطريقتَين StartAt()
وEndAt()
للحدّ من
النتائج إلى نطاق محدد من القيم.
وحتى في حالة وجود مطابقة واحدة فقط لطلب البحث، فستظل اللقطة قائمة فإنها تحتوي فقط على عنصر واحد.
تحديد عدد النتائج
يمكنك استخدام الطريقتَين LimitToFirst()
وLimitToLast()
لضبط
الحد الأقصى لعدد العناصر الثانوية المطلوب مزامنتها لمعاودة اتصال معيّنة. على سبيل المثال، إذا
إذا كنت تستخدم LimitToFirst()
لضبط الحدّ الأقصى المسموح به البالغ 100، لن تتلقّى إلا
إلى 100 طلب معاودة الاتصال من OnChildAdded
. إذا كان لديك أقل من 100 عنصر مخزن في
قاعدة بيانات Firebase، يتم تنشيط استدعاء OnChildAdded
لكل عنصر.
ومع تغيُّر العناصر، ستتلقّى OnChildAdded
عمليات معاودة الاتصال للعناصر التي تدخل في
وOnChildRemoved
عمليات استدعاء للعناصر التي تستخرج منها بحيث
يظل العدد الإجمالي 100.
على سبيل المثال، يعرض الرمز أدناه أعلى نتيجة من قائمة الصدارة:
firebase::database::Query query = dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1); // To get the resulting DataSnapshot either use query.GetValue() and poll the // future, or use query.AddValueListener() and register to handle the // OnValueChanged callback.
الفلترة حسب المفتاح أو القيمة
يمكنك استخدام StartAt()
وEndAt()
وEqualTo()
لاختيار الترتيب العشوائي.
نقاط البداية والنهاية والتكافؤ للاستعلامات. يمكن أن يكون هذا مفيدًا
البيانات على صفحات أو البحث عن عناصر بها أطفال لها قيمة محددة.
كيف يتم ترتيب بيانات طلبات البحث
يوضح هذا القسم كيفية فرز البيانات حسب كل طريقة من الطرق بالترتيب في
صف واحد (Query
).
OrderByChild
عند استخدام OrderByChild()
، تكون البيانات التي تحتوي على المفتاح الفرعي المحدّد هي
مرتبة على النحو التالي:
- تأتي العناصر الثانوية ذات القيمة
null
للمفتاح الفرعي المحدّد أولاً. - العناصر الثانوية بقيمة
false
للمفتاح الفرعي المحدّد لاحقًا. إذا كانت القيمةfalse
للعديد من العناصر الثانوية، يتم تمثيلها مرتبة معجميًا حسب المفتاح. - العناصر الثانوية بقيمة
true
للمفتاح الفرعي المحدّد لاحقًا. إذا كانت القيمةtrue
لعدة عناصر ثانويّة، سيتم مرتبة قاموسًا حسب المفتاح. - تأتي الأطفال ذوي القيمة الرقمية بعد ذلك، مرتبة بترتيب تصاعدي. في حال حذف تكون لعناصر فرعية متعددة نفس القيمة الرقمية للعنصر الفرعي المحدد يتم فرزها حسب المفتاح.
- تأتي السلاسل بعد الأرقام ويتم ترتيبها بشكل قاموس تصاعديًا. طلبك. إذا كانت هناك عدة عناصر ثانوية لها نفس القيمة للعنصر الفرعي المحدد يتم ترتيبها قاموسًا حسب المفتاح.
- تأتي الكائنات في النهاية ويتم فرزها قاموسًا حسب المفتاح بترتيب تصاعدي.
OrderByKey
عند استخدام OrderByKey()
لترتيب بياناتك، يتم عرض البيانات تصاعديًا.
بالمفتاح.
- تأتي العناصر الثانوية التي تتضمن مفتاحًا يمكن تحليله كعدد صحيح 32 بت أولاً، ويتم ترتيبها تصاعديًا.
- يأتي العناصر الثانوية التي لها قيمة سلسلة كمفتاحها بعد ذلك، ويتم فرزها ترتيبًا تصاعديًا.
OrderByValue
عند استخدام OrderByValue()
، يتم ترتيب العناصر الثانوية حسب قيمتها. ترتيب
هذه المعايير هي نفسها في OrderByChild()
، باستثناء قيمة العقدة
يتم استخدامه بدلاً من قيمة مفتاح فرعي محدد.