משחזר נתונים

מסמך זה מכסה את היסודות של אחזור נתונים וכיצד להזמין ולסנן נתוני Firebase.

לפני שאתה מתחיל

לפני שתוכל להשתמש במסד נתונים בזמן אמת , עליך:

  • רשום את פרויקט Unity שלך והגדר אותו לשימוש ב-Firebase.

    • אם פרויקט Unity שלך כבר משתמש ב-Firebase, אז הוא כבר רשום ומוגדר עבור Firebase.

    • אם אין לך פרויקט של Unity, תוכל להוריד אפליקציה לדוגמה .

  • הוסף את 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 כדי להירשם לשינויים בתוכן בנתיב נתון. אירוע זה מופעל פעם אחת כאשר המאזין מחובר ושוב בכל פעם שהנתונים, כולל ילדים, משתנים. ההתקשרות חזרה לאירוע מועברת תמונת מצב המכילה את כל הנתונים באותו מיקום, כולל נתוני ילדים. אם אין נתונים, תמונת המצב המוחזרת היא 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 callbacks. אם יש לך פחות מ-100 פריטים המאוחסנים במסד הנתונים שלך ב-Firebase, יופעל התקשרות חוזרת ChildAdded עבור כל פריט.

כאשר פריטים משתנים, אתה מקבל התקשרות חוזרת ChildAdded עבור פריטים שנכנסים לשאילתה ו- ChildRemoved callbacks עבור פריטים שנפלטים ממנה כך שהמספר הכולל נשאר על 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() , אלא שהערך של הצומת משמש במקום הערך של מפתח צאצא שצוין.