Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

تتناول هذه المستندات أساسيات استرداد البيانات وكيفية ترتيب بيانات Firebase وتصفيتها.

قبل البدء

قبل أن تتمكّن من استخدام Realtime Database, عليك تنفيذ ما يلي:

سجِّل مشروع Unity الخاص بك وأعدَّه لاستخدام Firebase.
- إذا كان مشروع Unity يستخدم Firebase حاليًا، يكون قد تم تسجيله وإعداده لاستخدام Firebase.
- إذا لم يكن لديك مشروع Unity، يمكنك تنزيل نموذج تطبيق.
أضِف حزمة Firebase Unity SDK (تحديدًا FirebaseDatabase.unitypackage) إلى مشروع Unity الخاص بك.

يُرجى العِلم أنّ إضافة Firebase إلى مشروع Unity تتضمّن مهامًا في كلّ من الـ Firebase console ومشروع 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 =&gt {
        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.

ترتيب البيانات وتصفيتها

يمكنك استخدام الفئة Realtime Database 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
    }

يحدّد هذا المثال طلب بحث يؤدي عند دمجه مع متتبِّع أحداث valuechanged إلى مزامنة العميل مع قائمة الصدارة في قاعدة البيانات، والتي يتم ترتيبها حسب النتيجة لكل إدخال. يمكنك قراءة المزيد عن تنظيم بياناتك بكفاءة في مقالة تنظيم قاعدة البيانات.

يحدّد استدعاء طريقة 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() ، باستثناء أنّه يتم استخدام قيمة العقدة بدلاً من قيمة مفتاح عنصر فرعي محدّد.