این سند اصول بازیابی داده ها و نحوه سفارش و فیلتر کردن داده های 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()
، داده هایی که حاوی کلید فرزند مشخص شده هستند به صورت زیر مرتب می شوند:
- کودکان با مقدار
null
برای کلید فرزند مشخص شده اول هستند. - کودکان با مقدار
false
برای کلید فرزند مشخص شده در مرحله بعدی قرار می گیرند. اگر چند فرزند مقدارfalse
داشته باشند، از نظر واژگانی بر اساس کلید مرتب می شوند. - کودکان با مقدار
true
برای کلید فرزند مشخص شده در مرحله بعدی قرار می گیرند. اگر چند فرزند مقدارtrue
داشته باشند، از نظر واژگانی بر اساس کلید مرتب می شوند. - کودکان با مقدار عددی در مرحله بعدی قرار می گیرند که به ترتیب صعودی مرتب شده اند. اگر چندین فرزند مقدار عددی یکسانی برای گره فرزند مشخص شده داشته باشند، آنها بر اساس کلید مرتب می شوند.
- رشته ها بعد از اعداد آمده و از نظر واژگانی به ترتیب صعودی مرتب شده اند. اگر چندین فرزند مقدار یکسانی برای گره فرزند مشخص شده داشته باشند، آنها از نظر واژگانی بر اساس کلید مرتب می شوند.
- اشیاء در آخر قرار می گیرند و از نظر واژگانی بر اساس کلید به ترتیب صعودی مرتب می شوند.
OrderByKey
هنگام استفاده از OrderByKey()
برای مرتب کردن داده های خود، داده ها به ترتیب صعودی بر اساس کلید بازگردانده می شوند.
- کودکان دارای کلیدی که می تواند به عنوان یک عدد صحیح 32 بیتی تجزیه شود، در درجه اول قرار می گیرند و به ترتیب صعودی مرتب می شوند.
- کودکان با مقدار رشته به عنوان کلید در مرحله بعدی قرار می گیرند که از نظر واژگانی به ترتیب صعودی مرتب شده اند.
OrderByValue
هنگام استفاده از OrderByValue()
، بچه ها بر اساس مقدارشان مرتب می شوند. معیارهای ترتیب مانند OrderByChild()
است، با این تفاوت که مقدار گره به جای مقدار کلید فرزند مشخص شده استفاده می شود.