این سند اصول بازیابی دادهها و نحوه سفارش و فیلتر کردن دادههای 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 => { 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 یکبار برای هر فرزند موجود و سپس هربار که فرزند جدیدی به مسیر مشخصشده اضافه میشود، مطرح میشود. The listener is passed a snapshot containing the new child's
data.
رویداد 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() برای تنظیم محدودیت ۱۰۰ استفاده کنید، در ابتدا فقط تا
۱۰۰ 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()
، دادههایی که حاوی کلید فرزند مشخصشده هستند بهصورت زیر مرتب میشوند:
- فرزندان با مقدار
nullبرای کلید فرزند مشخصشده اول میآیند. - فرزندان با مقدار
falseبرای کلید فرزند مشخصشده در ردیف بعدی قرار میگیرند. اگر چند فرزند مقدارfalseداشته باشند، براساس کلید بهترتیب الفبایی مرتب میشوند. - فرزندان با مقدار
trueبرای کلید فرزند مشخصشده در ردیف بعدی قرار میگیرند. اگر چند فرزند مقدارtrueداشته باشند، بهترتیب الفبایی براساس کلید مرتب میشوند. - فرزندان با مقدار عددی در ردیف بعدی قرار میگیرند و بهترتیب صعودی مرتب میشوند. اگر چندین فرزند مقدار عددی یکسانی برای گره فرزند مشخصشده داشته باشند، براساس کلید مرتب میشوند.
- رشتهها بعداز اعداد میآیند و بهترتیب صعودی واژهنگاری مرتب میشوند. اگر چند فرزند مقدار یکسانی برای گره فرزند مشخصشده داشته باشند، آنها بهصورت واژهنامهای براساس کلید مرتب میشوند.
- اشیاء در آخر میآیند و بهترتیب صعودی براساس کلید مرتب میشوند.
OrderByKey
هنگام استفاده از OrderByKey()
برای مرتبسازی دادهها، دادهها بهترتیب صعودی براساس کلید برگردانده میشوند.
- فرزندان با کلیدی که میتواند بهعنوان عدد صحیح ۳۲ بیتی تجزیه شود، ابتدا میآیند و بهترتیب صعودی مرتب میشوند.
- فرزندان با مقدار رشتهای بهعنوان کلیدشان در ردیف بعدی قرار میگیرند و بهترتیب صعودی واژهنامهای مرتب میشوند.
OrderByValue
هنگام استفاده از OrderByValue()
، فرزندان براساس مقدارشان مرتب میشوند. معیارهای ترتیببندی همانند
OrderByChild() است، با این تفاوت که بهجای مقدار کلید فرزند مشخصشده، از مقدار گره استفاده میشود.