אחזור נתונים

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

במאמר הזה נסביר איך מאחזרים נתונים ואיך ממיינים ומסננים נתונים ב-Firebase.

לפני שמתחילים

כדי להשתמש ב-Realtime Database, צריך:

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

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

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

• מוסיפים את Firebase Unity SDK (במיוחד את FirebaseDatabase.unitypackage) לפרויקט Unity.

שימו לב: הוספת Firebase לפרויקט ב-Unity כוללת משימות במסוף Firebase ובפרויקט הפתוח ב-Unity (לדוגמה, הורדה של קובצי תצורה של Firebase מהמסוף והעברה שלהם לפרויקט ב-Unity).

אחזור נתונים

הנתונים של Firebase מאוחזרים באמצעות קריאה חד-פעמית ל-GetValueAsync() או באמצעות צירוף לאירוע בהפניה FirebaseDatabase. הפונקציה event listener מופעלת פעם אחת עבור המצב הראשוני של הנתונים, ושוב בכל פעם שהנתונים משתנים.

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

מיון נתונים

כדי לאחזר נתונים ממוינים, צריך קודם לציין אחת משיטות המיון כדי לקבוע את סדר התוצאות:

אפשר להשתמש רק בשיטה אחת של מיון בכל פעם. הפעלת שיטה של מיון לפי סדר (order-by) מספר פעמים באותה שאילתה גורמת לשגיאה.

בדוגמה הבאה אפשר לראות איך נרשמים לטבלת לידרבורד של ניקוד, שמסודרת לפי ניקוד.

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

הקריאה ל-method‏ OrderByChild() מציינת את מפתח הילד כדי להזמין את התוצאות. במקרה הזה, התוצאות ממוינות לפי הערך של "score" value בכל צאצא. מידע נוסף על הסדר של סוגי נתונים אחרים זמין במאמר איך מסודרים נתוני שאילתות.

סינון נתונים

כדי לסנן נתונים, אפשר לשלב כל אחת מהשיטות של הגבלה או טווח עם שיטת מיון כשיוצרים שאילתה.

בניגוד לשיטות order-by, אפשר לשלב כמה פונקציות limit או range. לדוגמה, אפשר לשלב בין השיטות StartAt() ו-EndAt() כדי להגביל את התוצאות לטווח ערכים מסוים.

גם אם יש רק התאמה אחת לשאילתה, התמונה היא עדיין רשימה, רק שהיא מכילה פריט אחד.

הגבלת מספר התוצאות

אפשר להשתמש בשיטות LimitToFirst() ו-LimitToLast() כדי להגדיר מספר מקסימלי של ילדים שיסונכרנו עבור קריאה חוזרת (callback) נתונה. לדוגמה, אם משתמשים ב-LimitToFirst() כדי להגדיר מגבלה של 100, מקבלים בהתחלה רק עד 100 קריאות חוזרות של ChildAdded. אם יש לכם פחות מ-100 פריטים שמאוחסנים במסד הנתונים של Firebase, מתבצעת קריאה חוזרת (callback) של ChildAdded לכל פריט.

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

איך נתוני השאילתות מסודרים

בקטע הזה מוסבר איך הנתונים ממוינים לפי כל אחת מהשיטות של order-by במחלקה Query.

OrderByChild

כשמשתמשים ב-OrderByChild(), נתונים שמכילים את מפתח הצאצא שצוין מסודרים באופן הבא:

1. ילדים עם ערך null למפתח הילד שצוין מופיעים ראשונים.
2. אחריהם מופיעים רכיבי צאצא עם הערך false עבור מפתח הצאצא שצוין. אם לכמה צאצאים יש ערך של false, הם ממוינים לקסיקוגרפית לפי מפתח.
3. אחריהם מופיעים רכיבי צאצא עם הערך true עבור מפתח הצאצא שצוין. אם לכמה צאצאים יש ערך של true, הם ממוינים לפי מפתח בסדר לקסיקוגרפי.
4. אחריהם מופיעים ילדים עם ערך מספרי, ממוינים בסדר עולה. אם לכמה צאצאים יש את אותו ערך מספרי בצומת הצאצא שצוין, הם ממוינים לפי מפתח.
5. מחרוזות מופיעות אחרי מספרים וממוינות בסדר עולה לפי סדר מילוני. אם לכמה צאצאים יש את אותו ערך בצומת הצאצא שצוין, הם מסודרים לפי מפתח בסדר לקסיקוגרפי.
6. האובייקטים מופיעים בסוף וממוינים בסדר עולה לפי מפתח, בסדר לקסיקוגרפי.

OrderByKey

כשמשתמשים ב-OrderByKey() כדי למיין את הנתונים, הנתונים מוחזרים בסדר עולה לפי מפתח.

1. הילדים עם מפתח שאפשר לנתח כמספר שלם בן 32 ביט מופיעים ראשונים, בסדר עולה.
2. אחריהם מופיעים ילדים עם ערך מחרוזת כמפתח, ממוינים בסדר עולה לפי סדר מילוני.

OrderByValue

כשמשתמשים ב-OrderByValue(), הילדים מסודרים לפי הערך שלהם. קריטריוני המיון זהים לאלה שמופיעים ב-OrderByChild(), אלא שהערך של הצומת משמש במקום הערך של מפתח צאצא שצוין.