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

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

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

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

משחזר נתונים

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

קבל DatabaseReference

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

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

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

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&ltDataSnaphot&gt התוצאה מכילה את נתון במיקום שצוין באתר בעת האירוע. שיחות value() על תשואות מצלם בית Variant המייצג את הנתונים.

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

כיתת ChildListerer

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

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

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

מיין נתונים

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

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

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

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

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

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

סינון נתונים

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

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

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

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

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

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

כפריטים לשנות, שתקבל OnChildAdded הגיעו ליעדן עבור הפריטים הקלידו את השאילתא ואת OnChildRemoved הגיעו ליעדן עבור הפריטים להיפלט כך שהיות המספר הכולל ב 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 , הם מסודרים lexicographically ידי מפתח.
  3. ילדים עם ערך של true עבור מפתח הבן שצוין לבוא הבאים. אם ילדים מרובים יש ערך של true , הם מסודרים lexicographically ידי מפתח.
  4. ילדים עם ערך מספרי מגיעים אחר כך, ממוינים בסדר עולה. אם למספר ילדים יש ערך מספרי זהה לצומת הילד שצוין, הם ממוינים לפי מפתח.
  5. מחרוזות באות אחרי מספרים וממוינות בלקסיקוגרפיה בסדר עולה. אם למספר ילדים יש ערך זהה לצומת הילד שצוין, הם מסודרים לקסיקוגרפית לפי מפתח.
  6. אובייקטים מגיעים אחרונים וממיינים בלקסיקוגרפיה לפי מפתח בסדר עולה.

OrderByKey

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

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

OrderByValue

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

הצעדים הבאים