درحال بازیابی داده‌ها

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

قبل از شروع

پیش‌از اینکه بتوانید از Realtime Database استفاده کنید، باید:

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

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

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

• Firebase Unity SDK (به‌طور خاص، 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 =&gt {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

گوش دادن به رویدادها

می‌توانید شنوندگان رویداد را برای مشترک شدن در تغییرات داده‌ها اضافه کنید:

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

مرتب کردن داده‌ها

برای بازیابی داده‌های مرتب‌شده، ابتدا یکی از روش‌های به‌ترتیب کردن را برای تعیین نحوه مرتب‌سازی نتایج مشخص کنید:

در هر زمان فقط می‌توانید از یک روش به‌ترتیب کردن استفاده کنید. فراخوانی روش به‌ترتیب کردن به‌دفعات در یک پُرسمان باعث ایجاد خطا می‌شود.

مثال زیر نشان می‌دهد که چگونه می‌توانید در جدول رده‌بندی امتیاز که براساس امتیاز مرتب شده است مشترک شوید.

      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" در هر فرزند مرتب می‌شود. برای اطلاعات بیشتر درباره نحوه مرتب‌سازی انواع دیگر داده‌ها، نحوه مرتب‌سازی داده‌های پُرسمان را ببینید.

فیلتر کردن داده‌ها

برای فیلتر کردن داده‌ها، می‌توانید هریک از روش‌های محدود کردن یا محدوده را با یک روش به‌ترتیب کردن هنگام ساختن پرسمان ترکیب کنید.

برخلاف روش‌های به‌ترتیب کردن، می‌توانید چندین تابع محدوده یا حد را ترکیب کنید. برای مثال، می‌توانید روش‌های StartAt() و EndAt() را ترکیب کنید تا نتایج را به گستره مشخصی از مقادیر محدود کنید.

حتی وقتی فقط یک مورد منطبق برای پُرسمان وجود دارد، خلاصه همچنان یک فهرست است؛ فقط یک مورد دارد.

محدود کردن تعداد نتایج

می‌توانید از روش‌های LimitToFirst() و LimitToLast() برای تنظیم حداکثر تعداد فرزندان برای همگام‌سازی برای یک فراخوانی معین استفاده کنید. برای مثال، اگر از LimitToFirst() برای تنظیم محدودیت ۱۰۰ استفاده کنید، در ابتدا فقط تا ۱۰۰ ChildAdded فراخوانی برگشتی دریافت می‌کنید. اگر کمتر از ۱۰۰ مورد در پایگاه داده Firebase شما ذخیره شده باشد، یک فراخوانی برگشتی ChildAdded برای هر مورد اجرا می‌شود.

با تغییر موارد، ChildAdded فراخوانی برگشتی برای مواردی که وارد پُرسمان می‌شوند و ChildRemoved فراخوانی برگشتی برای مواردی که از آن خارج می‌شوند دریافت می‌کنید تا تعداد کل روی ۱۰۰ باقی بماند.

برای مثال، کد زیر بالاترین امتیاز را از تابلو پیشتازان برمی‌گرداند:

      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. فرزندان با کلیدی که می‌تواند به‌عنوان عدد صحیح ۳۲ بیتی تجزیه شود، ابتدا به‌صورت صعودی مرتب می‌شوند.
2. فرزندانی که مقدار رشته‌ای به‌عنوان کلید دارند در ردیف بعدی قرار می‌گیرند و به‌ترتیب صعودی واژه‌نامه‌ای مرتب می‌شوند.

OrderByValue

هنگام استفاده از OrderByValue() ، فرزندان براساس مقدارشان مرتب می‌شوند. معیارهای ترتیب‌بندی همانند OrderByChild() است، با این تفاوت که به‌جای مقدار کلید فرزند مشخص‌شده، از مقدار گره استفاده می‌شود.