جارٍ استرداد البيانات

يتناول هذا المستند أساسيات استرداد البيانات وكيفية الترتيب والتصفية بيانات 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 لاسترداد البيانات المُرتَّبة حسب مفتاح أو حسب القيمة أو حسب القيمة التابعة لفرد. يمكنك أيضًا فلترة النتيجة التي تم فرزها إلى عدد محدد من النتائج أو مجموعة من المفاتيح أو القيم.

فرز البيانات

لاسترداد البيانات التي تم فرزها، ابدأ بتحديد إحدى طرق الترتيب حسب لتحديد كيفية ترتيب النتائج:

الطريقة	الاستخدام
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()، تكون البيانات التي تحتوي على المفتاح الفرعي المحدّد هي مرتبة على النحو التالي:

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

OrderByKey

عند استخدام OrderByKey() لترتيب بياناتك، يتم عرض البيانات تصاعديًا. بالمفتاح.

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

OrderByValue

عند استخدام OrderByValue()، يتم ترتيب العناصر الثانوية حسب قيمتها. ترتيب هذه المعايير هي نفسها في OrderByChild()، باستثناء قيمة العقدة يتم استخدامه بدلاً من قيمة مفتاح فرعي محدد.