يتناول هذا المستند أساسيات استرداد البيانات وكيفية الترتيب والتصفية بيانات Firebase.
قبل البدء
قبل أن تتمكّن من استخدام Realtime Database, عليك إجراء ما يلي:
سجِّل مشروعك على Unity واضبطه لاستخدام Firebase.
إذا كان مشروعك في Unity يستخدم Firebase حاليًا، يكون تسجيلها وإعدادها لمنصة Firebase
وإذا لم يكن لديك مشروع Unity، يمكنك تنزيل نموذج تطبيق.
أضِف حزمة تطوير البرامج (SDK) لنظام التشغيل Unity Firebase (خاصةً
FirebaseDatabase.unitypackage
) إلى لمشروع Unity الخاص بك.
تجدر الإشارة إلى أنّ إضافة منصة Firebase إلى مشروع Unity تتضمّن مهامًا في كلّ من وحدة تحكّم Firebase وفي مشروع Unity المفتوح (على سبيل المثال، يمكنك تنزيل ملفات تهيئة Firebase من وحدة التحكم، ثم نقل إلى مشروع Unity).
جارٍ استرداد البيانات
يتم استرداد بيانات Firebase إما عن طريق استدعاء لمرة واحدة إلى GetValueAsync() أو
إرفاقها بحدث في مرجع FirebaseDatabase
أداة معالجة الحدث هي
مرة واحدة للحالة الأولية للبيانات ومرة أخرى في أي وقت تتغير فيه البيانات.
الحصول على DatabaseReference
لقراءة البيانات من قاعدة البيانات، أنت بحاجة إلى نسخة افتراضية من DatabaseReference
:
using Firebase; using Firebase.Database; using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread public class MyScript: MonoBehaviour { void Start() { // Get the root reference location of the database. DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference; } }
قراءة البيانات مرة واحدة
ويمكنك استخدام الطريقة GetValueAsync
لقراءة نبذة ثابتة عن
والمحتوى في مسار معين مرة واحدة. ستتضمّن نتيجة المهمة لقطة
الذي يتضمن جميع البيانات في هذا الموقع، بما في ذلك البيانات الفرعية. إذا لم تكن هناك بيانات،
اللقطة التي يتم عرضها هي null
.
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .GetValueAsync().ContinueWithOnMainThread(task => { if (task.IsFaulted) { // Handle the error... } else if (task.IsCompleted) { DataSnapshot snapshot = task.Result; // Do something with snapshot... } });
الاستماع إلى الأحداث
يمكنك إضافة أدوات معالجة الأحداث للاشتراك في التغييرات التي تطرأ على البيانات:
الحدث | معدّل الاستخدام |
---|---|
ValueChanged |
قراءة التغييرات التي تتم على محتوى المسار بالكامل والاستماع إليها |
ChildAdded
| استرداد قوائم العناصر أو الاستماع إلى الإضافات إلى قائمة من العناصر.
الاستخدام المقترَح مع ChildChanged و
ChildRemoved لمراقبة التغييرات في القوائم. |
ChildChanged |
رصد التغييرات على العناصر في القائمة الاستخدام مع
ChildAdded وChildRemoved للمراقبة
التغييرات على القوائم. |
ChildRemoved |
رصد العناصر التي تتم إزالتها من القائمة الاستخدام مع
ChildAdded وChildChanged للمراقبة
التغييرات على القوائم. |
ChildMoved |
الاستماع إلى التغييرات التي تطرأ على ترتيب العناصر في قائمة مع ترتيب
تتبَع ChildMoved أحداث دائمًا
حدث واحد (ChildChanged ) تسبب في طلب العنصر
تغيير (بناءً على طريقة الترتيب الحالية). |
حدث ValueChanged
يمكنك استخدام الحدث ValueChanged
للاشتراك في خدمة تلقّي إشعارات بشأن تغييرات
والمحتوى في مسار معين. يتم تشغيل هذا الحدث مرة واحدة عندما يكون المستمع
ومرة أخرى في كل مرة تتغير فيها البيانات، بما في ذلك الأطفال. ويتم تمرير استدعاء الحدث نبذة تحتوي على جميع البيانات في هذا الموقع، بما في ذلك
البيانات الفرعية. إذا لم تتوفّر بيانات، ستكون النبذة التي يتم عرضها هي null
.
يوضح المثال التالي لعبة تسترد نتائج لوحة صدارة من قاعدة البيانات:
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
ValueChangedEventArgs
يحتوي على DataSnapshot
الذي يحتوي على البيانات في
الموقع المحدد في قاعدة البيانات وقت الحدث. جارٍ الاتصال بالرقم Value
في إحدى اللقطات، يتم عرض الرمز Dictionary<string, object>
الذي يمثل البيانات.
وفي حال عدم توفّر بيانات في الموقع الجغرافي، يعرض الاتصال بـ Value
القيمة null
.
في هذا المثال، يتم فحص args.DatabaseError
أيضًا لمعرفة ما إذا كانت القراءة
تم إلغاؤه. على سبيل المثال، يمكن إلغاء القراءة إذا لم يكن لدى العميل
إذن للقراءة من موقع قاعدة بيانات Firebase. وستشير DatabaseError
إلى سبب حدوث الفشل.
يمكنك لاحقًا إلغاء الاشتراك في الحدث باستخدام أي DatabaseReference
يحتوي على
على نفس المسار. DatabaseReference
أمثلة مؤقتة ويمكن التفكير فيها
كطريقة للوصول إلى أي مسار واستعلام.
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged. }
الأحداث الثانوية
يتم تشغيل الأحداث الفرعية استجابةً لعمليات محددة تحدث في
العناصر الثانوية لعقدة من أي عملية، مثل إضافة عنصر ثانوي جديد من خلال
طريقة Push()
أو بيانات فرعية يتم تعديلها من خلال UpdateChildrenAsync()
. ويمكن أن تكون كلٌّ من هذه الأدوات معًا مفيدة للاستماع إلى التغييرات في
عقدة معينة في قاعدة بيانات. على سبيل المثال، قد تستخدم إحدى الألعاب هذه الطرق
معًا لمراقبة النشاط في التعليقات على جلسة اللعبة، كما هو موضّح أدناه:
var ref = FirebaseDatabase.DefaultInstance .GetReference("GameSessionComments"); ref.ChildAdded += HandleChildAdded; ref.ChildChanged += HandleChildChanged; ref.ChildRemoved += HandleChildRemoved; ref.ChildMoved += HandleChildMoved; } void HandleChildAdded(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildChanged(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildRemoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildMoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
يُستخدَم حدث ChildAdded
عادةً لاسترداد قائمة
العناصر في قاعدة بيانات Firebase. تم رفع الحدث ChildAdded
مرة واحدة
لكل طفل حالي ثم مرة أخرى في كل مرة تتم فيها إضافة طفل جديد إلى
المسار المحدد. يتم السماح للمستمِع بأخذ لقطة تحتوي على الطفل الجديد
البيانات.
يتم رفع حدث ChildChanged
في أي وقت يتم فيه تعديل عقدة فرعية.
يتضمن ذلك أي تعديلات على العناصر التابعة للعقدة الفرعية. من المهم
يتم استخدامه عادةً مع ChildAdded
وChildRemoved
.
الأحداث للاستجابة للتغييرات التي تطرأ على قائمة من العناصر. تم تمرير اللقطة إلى
يحتوي أداة معالجة الأحداث على البيانات المحدَّثة الخاصة بالفرع.
يتم تشغيل حدث ChildRemoved
عند إزالة عنصر ثانوي فوري.
ويتم استخدامها عادةً مع ChildAdded
و
ChildChanged
طلبات معاودة الاتصال. تحتوي اللقطة التي يتم تمريرها إلى معاودة الاتصال بالحدث على
بيانات العنصر الثانوي الذي تمت إزالته.
يتم تشغيل حدث ChildMoved
عند وقوع حدث ChildChanged
من خلال تحديث يؤدي إلى إعادة ترتيب العنصر الثانوي. من المهم
مع البيانات المطلوبة باستخدام OrderByChild
أو OrderByValue
.
فرز البيانات وتصفيتها
يمكنك استخدام الفئة Query
التي تتضمّن Realtime Database لاسترداد بيانات مرتّبة حسب.
مفتاح أو حسب القيمة أو حسب القيمة الفرعية. يمكنك أيضًا فلترة
النتيجة التي تم فرزها إلى عدد محدد من النتائج أو مجموعة من المفاتيح أو
القيم.
فرز البيانات
لاسترداد البيانات التي تم فرزها، ابدأ بتحديد إحدى طرق الترتيب حسب لتحديد كيفية ترتيب النتائج:
الطريقة | الاستخدام |
---|---|
OrderByChild() |
يمكنك ترتيب النتائج حسب قيمة مفتاح فرعي محدّد. |
OrderByKey()
| يمكنك ترتيب النتائج حسب المفاتيح الثانوية. |
OrderByValue() |
ترتيب النتائج حسب القيم الثانوية |
يمكنك استخدام طريقة واحدة فقط لكل طلب على حدة في كل مرة. استدعاء طريقة الطلب حسب عدة مرات في نفس الاستعلام يؤدي إلى حدوث خطأ.
يوضح المثال التالي كيفية الاشتراك في إحدى النتائج. قائمة الصدارة مرتبة حسب النتيجة
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
يحدِّد ذلك طلب بحث عند دمجه مع أداة معالجة حدث ذو قيمة مُتغيّرة. يقوم بمزامنة البرنامج مع ليدربورد في قاعدة البيانات، مرتبة حسب لكل إدخال. يمكنك قراءة المزيد حول هيكلة بياناتك بكفاءة في تنظيم قاعدة البيانات.
يحدد استدعاء طريقة OrderByChild()
المفتاح الفرعي لترتيب
النتائج حسب. في هذه الحالة، يتم ترتيب النتائج حسب قيمة "score"
قيمة في كل فرع. لمزيد من المعلومات حول كيفية ترتيب أنواع البيانات الأخرى،
راجِع كيفية ترتيب بيانات طلبات البحث.
تصفية البيانات
لتصفية البيانات، يمكنك دمج أي من طرق الحد أو النطاق مع الترتيب حسب عند إنشاء استعلام.
الطريقة | الاستخدام |
---|---|
LimitToFirst() |
لتعيين الحد الأقصى لعدد العناصر المراد عرضها من بداية قائمة نتائج مرتبة. |
LimitToLast() |
لضبط الحد الأقصى لعدد السلع المطلوب عرضها من نهاية طلب الشراء قائمة بالنتائج. |
StartAt() |
عرض عناصر أكبر من أو تساوي المفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
EndAt() |
إرجاع عناصر أقل من أو تساوي المفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
EqualTo() |
إرجاع عناصر مساوية للمفتاح أو القيمة المحددة اعتمادًا على الطريقة المختارة. |
على عكس طرق الترتيب حسب، يمكنك الجمع بين دوال متعددة للحدود أو النطاقات.
على سبيل المثال، يمكنك الجمع بين الطريقتَين StartAt()
وEndAt()
للحدّ من
النتائج إلى نطاق محدد من القيم.
وحتى في حالة وجود مطابقة واحدة فقط لطلب البحث، فستظل اللقطة قائمة فإنها تحتوي فقط على عنصر واحد.
تحديد عدد النتائج
يمكنك استخدام الطريقتَين LimitToFirst()
وLimitToLast()
لضبط
الحد الأقصى لعدد العناصر الثانوية المطلوب مزامنتها لمعاودة اتصال معيّنة. على سبيل المثال، إذا
إذا كنت تستخدم LimitToFirst()
لضبط الحدّ الأقصى المسموح به البالغ 100، لن تتلقّى إلا في البداية
إلى 100 طلب معاودة الاتصال من ChildAdded
. إذا كان لديك أقل من 100 عنصر مخزن في
قاعدة بيانات Firebase، يتم تنشيط استدعاء ChildAdded
لكل عنصر.
ومع تغيُّر العناصر، ستتلقّى ChildAdded
عمليات معاودة الاتصال للعناصر التي تدخل في
وChildRemoved
عمليات استدعاء للعناصر التي تستخرج منها بحيث
يظل العدد الإجمالي 100.
على سبيل المثال، يعرض الرمز أدناه أعلى نتيجة من قائمة الصدارة:
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score").LimitToLast(1) .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
الفلترة حسب المفتاح أو القيمة
يمكنك استخدام StartAt()
وEndAt()
وEqualTo()
لاختيار الترتيب العشوائي.
نقاط البداية والنهاية والتكافؤ للاستعلامات. يمكن أن يكون هذا مفيدًا
البيانات على صفحات أو البحث عن عناصر بها أطفال لها قيمة محددة.
كيف يتم ترتيب بيانات طلبات البحث
يوضح هذا القسم كيفية فرز البيانات حسب كل طريقة من الطرق بالترتيب في
صف واحد (Query
).
OrderByChild
عند استخدام OrderByChild()
، تكون البيانات التي تحتوي على المفتاح الفرعي المحدّد هي
مرتبة على النحو التالي:
- تأتي العناصر الثانوية بقيمة
null
للمفتاح الفرعي المحدّد أولاً. - العناصر الثانوية بقيمة
false
للمفتاح الفرعي المحدّد لاحقًا. إذا كانت القيمةfalse
للعديد من العناصر الثانوية، يتم تمثيلها مرتبة معجميًا حسب المفتاح. - العناصر الثانوية بقيمة
true
للمفتاح الفرعي المحدّد لاحقًا. إذا كانت القيمةtrue
لعدة عناصر ثانويّة، سيتم مرتبة قاموسًا حسب المفتاح. - تأتي الأطفال ذوي القيمة الرقمية بعد ذلك، مرتبة بترتيب تصاعدي. في حال حذف تكون لعناصر فرعية متعددة نفس القيمة الرقمية للعنصر الفرعي المحدد يتم فرزها حسب المفتاح.
- تأتي السلاسل بعد الأرقام ويتم ترتيبها بشكل قاموس تصاعديًا. طلبك. إذا كانت هناك عدة عناصر ثانوية لها نفس القيمة للعنصر الفرعي المحدد يتم ترتيبها قاموسًا حسب المفتاح.
- تأتي الكائنات في النهاية ويتم فرزها لغويًا حسب المفتاح بترتيب تصاعدي.
OrderByKey
عند استخدام OrderByKey()
لترتيب بياناتك، يتم عرض البيانات تصاعديًا.
بالمفتاح.
- تأتي العناصر الثانوية التي تتضمن مفتاحًا يمكن تحليله كعدد صحيح 32 بت أولاً، ويتم ترتيبها تصاعديًا.
- يأتي العناصر الثانوية التي لها قيمة سلسلة كمفتاحها بعد ذلك، ويتم فرزها ترتيبًا تصاعديًا.
OrderByValue
عند استخدام OrderByValue()
، يتم ترتيب العناصر الثانوية حسب قيمتها. ترتيب
هذه المعايير هي نفسها في OrderByChild()
، باستثناء قيمة العقدة
يتم استخدامه بدلاً من قيمة مفتاح فرعي محدد.