بازیابی داده ها

این سند اصول بازیابی داده ها و نحوه سفارش و فیلتر کردن داده های Firebase را پوشش می دهد.

قبل از شروع

قبل از اینکه بتوانید از Realtime Database استفاده کنید، باید:

• پروژه Unity خود را ثبت کرده و آن را برای استفاده از Firebase پیکربندی کنید.

  • اگر پروژه Unity شما قبلاً از Firebase استفاده می‌کند، پس از قبل برای Firebase ثبت و پیکربندی شده است.

  • اگر پروژه یونیتی ندارید، می توانید یک برنامه نمونه دانلود کنید.

• Firebase Unity SDK (به طور خاص FirebaseDatabase.unitypackage ) را به پروژه Unity خود اضافه کنید.

توجه داشته باشید که افزودن Firebase به پروژه Unity شما شامل وظایفی در کنسول Firebase و پروژه Unity باز شما می شود (به عنوان مثال، فایل های پیکربندی Firebase را از کنسول دانلود می کنید، سپس آنها را به پروژه Unity خود منتقل می کنید).

بازیابی داده ها

داده‌های Firebase یا با یک تماس یک‌باره به GetValueAsync() یا پیوست کردن به یک رویداد در مرجع FirebaseDatabase بازیابی می‌شوند. شنونده رویداد یک بار برای وضعیت اولیه داده ها و بار دیگر هر زمان که داده ها تغییر کند فراخوانی می شود.

یک مرجع پایگاه داده دریافت کنید

برای خواندن داده ها از پایگاه داده، به یک نمونه از 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 سفارش داده شده اند استفاده می شود.

مرتب سازی و فیلتر کردن داده ها

می توانید از کلاس 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
    }

این یک پرس و جو را تعریف می کند که هنگامی که با شنونده رویداد تغییر یافته ترکیب می شود، مشتری را با تابلوی امتیازات در پایگاه داده هماهنگ می کند، که بر اساس امتیاز هر ورودی مرتب می شود. می‌توانید در مورد ساختاردهی کارآمد داده‌های خود در Structure Your Database اطلاعات بیشتری کسب کنید.

فراخوانی متد 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() است، با این تفاوت که مقدار گره به جای مقدار کلید فرزند مشخص شده استفاده می شود.