אחזור נתונים עם Firebase Realtime Database עבור C++

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

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

ודא שהגדרת את האפליקציה שלך ואתה יכול לגשת למסד הנתונים כפי שמופיע במדריך Get Started .

משחזר נתונים

נתוני Firebase מאוחזרים על ידי קריאה חד פעמית ל- GetValue() או צירוף ל- ValueListener בהפניה ל- FirebaseDatabase . מאזין הערך נקרא פעם אחת עבור המצב ההתחלתי של הנתונים ושוב בכל פעם שהנתונים משתנים.

קבל הפניית מסד נתונים

כדי לכתוב נתונים למסד הנתונים, אתה צריך מופע של DatabaseReference :

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

קרא נתונים פעם אחת

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

  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").GetValue();

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

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

זה מראה כמה בדיקת שגיאות בסיסית, עיין ב- firebase::Future reference למידע נוסף על בדיקת שגיאות, ודרכים לקבוע מתי התוצאה מוכנה.

האזינו לאירועים

אתה יכול להוסיף מאזינים להירשם על שינויים בנתונים:

מחלקת הבסיס ValueListener

התקשר חזרה	שימוש אופייני
OnValueChanged	קרא והקשב לשינויים בכל התוכן של נתיב.

שיעור בסיס OnChildListener

OnChildAdded	אחזר רשימות של פריטים או האזן לתוספות לרשימת פריטים. מומלץ להשתמש עם OnChildChanged ו- OnChildRemoved כדי לעקוב אחר שינויים ברשימות.
OnChildChanged	האזן לשינויים בפריטים ברשימה. השתמש עם OnChildAdded ו- OnChildRemoved כדי לעקוב אחר שינויים ברשימות.
OnChildRemoved	האזן לפריטים שהוסרו מרשימה. השתמש עם OnChildAdded ו- OnChildChanged כדי לעקוב אחר שינויים ברשימות.
OnChildMoved	האזן לשינויים בסדר הפריטים ברשימה מסודרת. התקשרויות חוזרות OnChildMoved תמיד עוקבות אחר ההתקשרות חוזרת OnChildChanged עקב שינוי ההזמנה של הפריט (בהתבסס על השיטה הנוכחית שלך לפי הזמנה).

שיעור ValueListener

אתה יכול להשתמש בהתקשרויות חוזרות OnValueChanged כדי להירשם לשינויים בתוכן בנתיב נתון. התקשרות חוזרת זו מופעלת פעם אחת כאשר המאזין מחובר ושוב בכל פעם שהנתונים, כולל ילדים, משתנים. ההתקשרות חזרה מועברת תמונת מצב המכילה את כל הנתונים באותו מיקום, כולל נתוני ילדים. אם אין נתונים, תמונת המצב המוחזרת היא null .

הדוגמה הבאה מדגימה משחק המאחזר את התוצאות של לוח תוצאות ממסד הנתונים:

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

תוצאת Future&ltDataSnapshot&gt מכילה את הנתונים במיקום שצוין במסד הנתונים בזמן האירוע. קריאת value() בתמונת מצב מחזירה Variant המייצג את הנתונים.

בדוגמה זו, השיטה OnCancelled נדחפת גם כדי לראות אם הקריאה מבוטלת. לדוגמה, ניתן לבטל קריאה אם ​​ללקוח אין הרשאה לקרוא ממיקום מסד נתונים של Firebase. database::Error יציין מדוע התרחש הכשל.

כיתת ChildListener

אירועי צאצא מופעלים בתגובה לפעולות ספציפיות שקורות לילדים של צומת מפעולה כגון ילד חדש שנוסף באמצעות שיטת PushChild() או ילד המתעדכן באמצעות שיטת UpdateChildren() . כל אחד מהם ביחד יכול להיות שימושי להאזנה לשינויים בצומת ספציפי במסד נתונים. לדוגמה, משחק עשוי להשתמש בשיטות אלה יחד כדי לעקוב אחר פעילות בהערות של סשן משחק, כפי שמוצג להלן:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future<firebase::database::DataSnapshot> result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

ההתקשרות חזרה OnChildAdded משמשת בדרך כלל כדי לאחזר רשימה של פריטים במסד נתונים של Firebase. ההתקשרות חזרה OnChildAdded נקראת פעם אחת עבור כל ילד קיים ואז שוב בכל פעם שילד חדש נוסף לנתיב שצוין. למאזין מועברת תמונת מצב המכילה את הנתונים של הילד החדש.

ההתקשרות חזרה OnChildChanged נקראת בכל פעם שצומת צאצא משתנה. זה כולל שינויים כלשהם בצאצאים של צומת הילד. הוא משמש בדרך כלל בשילוב עם הקריאות OnChildAdded ו- OnChildRemoved כדי להגיב לשינויים ברשימת פריטים. תמונת המצב שהועברה למאזין מכילה את הנתונים המעודכנים עבור הילד.

ההתקשרות חזרה OnChildRemoved מופעלת כאשר צאצא מיידי מוסר. הוא משמש בדרך כלל בשילוב עם ההתקשרות חזרה OnChildAdded ו- OnChildChanged . תמונת המצב שהועברה להתקשרות חזרה מכילה את הנתונים עבור הילד שהוסר.

ההתקשרות חזרה OnChildMoved מופעלת בכל פעם שהשיחה OnChildChanged מועלית על ידי עדכון שגורם לסדר מחדש של הילד. הוא משמש עם נתונים המוזמנים עם OrderByChild או OrderByValue .

מיון וסינון נתונים

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

מיון נתונים

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

שיטה	נוֹהָג
OrderByChild()	סדר את התוצאות לפי הערך של מפתח צאצא שצוין.
OrderByKey()	הזמנת תוצאות לפי מפתחות ילדים.
OrderByValue()	סדר תוצאות לפי ערכי צאצא.

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

הדוגמה הבאה מדגימה כיצד אתה יכול להירשם ל-leaderboard לפי ציון.

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

זה מגדיר firebase::Query שבשילוב עם ValueListener מסנכרן את הלקוח עם ה-leaderboard במסד הנתונים, לפי הניקוד של כל ערך. תוכל לקרוא עוד על מבנה הנתונים שלך ביעילות ב- Structure Your Database .

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

סינון נתונים

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

שיטה	נוֹהָג
LimitToFirst()	מגדיר את המספר המרבי של פריטים להחזרה מתחילת רשימת התוצאות המסומנת.
LimitToLast()	מגדיר את המספר המרבי של פריטים להחזרה מסוף רשימת התוצאות שהוזמנה.
StartAt()	החזר פריטים הגדולים או שווה למפתח או לערך שצוינו בהתאם לשיטה לפי הזמנה שנבחרה.
EndAt()	החזר פריטים הנמוכים או שווה למפתח או לערך שצוינו בהתאם לשיטה לפי הזמנה שנבחרה.
EqualTo()	החזר פריטים השווים למפתח או לערך שצוינו בהתאם לשיטה לפי הזמנה שנבחרה.

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

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

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

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

כאשר פריטים משתנים, אתה מקבל התקשרות חוזרת OnChildAdded עבור פריטים שנכנסים לשאילתה ו- OnChildRemoved callbacks עבור פריטים שנפלטים ממנה כך שהמספר הכולל יישאר על 100.

לדוגמה, הקוד שלהלן מחזיר את הציון העליון מלוח הישגים:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

סנן לפי מפתח או ערך

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

הצעדים הבאים

• שמירת נתונים