การเรียกข้อมูลด้วยฐานข้อมูลเรียลไทม์ของ Firebase สำหรับ C++

เอกสารนี้ครอบคลุมข้อมูลพื้นฐานเกี่ยวกับการดึงข้อมูล รวมถึงวิธีจัดเรียงและกรองข้อมูล Firebase

ก่อนเริ่มต้น

ตรวจสอบว่าคุณได้ตั้งค่าแอปและเข้าถึงฐานข้อมูลได้ตามที่อธิบายไว้ใน Get Startedคู่มือ

กำลังดึงข้อมูล

ระบบจะดึงข้อมูล Firebase โดยการเรียก GetValue() เพียงครั้งเดียว หรือแนบกับ ValueListener ในการอ้างอิง FirebaseDatabase ระบบจะเรียก Listener ค่า 1 ครั้งสำหรับสถานะเริ่มต้นของข้อมูล และอีกครั้งทุกครั้งที่ข้อมูลมีการเปลี่ยนแปลง

รับ DatabaseReference

หากต้องการเขียนข้อมูลลงในฐานข้อมูล คุณต้องมีอินสแตนซ์ของ DatabaseReference ดังนี้

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

อ่านข้อมูล 1 ครั้ง

คุณสามารถใช้วิธี GetValue() เพื่ออ่านสแนปชอตแบบคงที่ของเนื้อหาในเส้นทางที่กำหนด 1 ครั้ง ผลลัพธ์ของงานจะมีสแนปชอตที่มีข้อมูลทั้งหมดในตำแหน่งดังกล่าว รวมถึงข้อมูลย่อย หากไม่มีข้อมูล สแนปชอตที่แสดงผลจะเป็น null

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

ณ จุดที่ส่งคำขอแล้ว แต่เราต้องรอให้ Future เสร็จสมบูรณ์ก่อนจึงจะอ่านค่าได้ เนื่องจากเกมมักจะทำงานในลูปและมีการเรียกกลับน้อยกว่าแอปพลิเคชันอื่นๆ คุณจึงมักจะโพลเพื่อดูว่าการทำงานเสร็จสมบูรณ์แล้วหรือยัง

  // 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 เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการตรวจสอบข้อผิดพลาดและวิธีพิจารณาว่าผลลัพธ์พร้อมแล้วเมื่อใด

ฟังเหตุการณ์

คุณสามารถเพิ่ม Listener เพื่อสมัครรับข้อมูลการเปลี่ยนแปลงข้อมูลได้ดังนี้

คลาสพื้นฐาน ValueListener

คลาสพื้นฐาน OnChildListener

คลาส ValueListener

คุณสามารถใช้การเรียกกลับ OnValueChanged เพื่อสมัครรับข้อมูลการเปลี่ยนแปลงเนื้อหาในเส้นทางที่กำหนด ระบบจะทริกเกอร์การเรียกกลับนี้ 1 ครั้งเมื่อแนบ Listener และอีกครั้งทุกครั้งที่ข้อมูลมีการเปลี่ยนแปลง ซึ่งรวมถึงข้อมูลย่อย ระบบจะส่งสแนปชอตที่มีข้อมูลทั้งหมดในตำแหน่งดังกล่าว รวมถึงข้อมูลย่อยไปยังการเรียกกลับ หากไม่มีข้อมูล สแนปชอตที่แสดงผลจะเป็น 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&ltfirebase::database::DataSnapshot&gt 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

โดยปกติแล้ว การเรียกกลับ OnChildAdded จะใช้เพื่อดึงข้อมูลรายการในฐานข้อมูล Firebase ระบบจะเรียกการเรียกกลับ OnChildAdded 1 ครั้งสำหรับข้อมูลย่อยที่มีอยู่แต่ละรายการ และอีกครั้งทุกครั้งที่มีการเพิ่มข้อมูลย่อยใหม่ลงในเส้นทางที่ระบุ ระบบจะส่งสแนปชอตที่มีข้อมูลของข้อมูลย่อยใหม่ไปยัง Listener

ระบบจะเรียกการเรียกกลับ OnChildChanged ทุกครั้งที่มีการแก้ไขโหนดย่อย ซึ่งรวมถึงการแก้ไขผู้สืบทอดของโหนดย่อย โดยปกติแล้ว จะใช้ร่วมกับการเรียก OnChildAdded และ OnChildRemoved เพื่อตอบสนองต่อการเปลี่ยนแปลงรายการ สแนปชอตที่ส่งไปยัง Listener จะมีข้อมูลที่อัปเดตสำหรับข้อมูลย่อย

ระบบจะทริกเกอร์การเรียกกลับ OnChildRemoved เมื่อมีการนำข้อมูลย่อยโดยตรงออก โดยปกติแล้ว จะใช้ร่วมกับการเรียกกลับ OnChildAdded และ OnChildChanged สแนปชอตที่ส่งไปยังการเรียกกลับจะมีข้อมูลสำหรับข้อมูลย่อยที่นำออก

ระบบจะทริกเกอร์การเรียกกลับ OnChildMoved ทุกครั้งที่การเรียก OnChildChanged เกิดขึ้นจากการอัปเดตที่ทำให้มีการจัดลำดับข้อมูลย่อยใหม่ โดยจะใช้กับข้อมูลที่จัดเรียงด้วย OrderByChild หรือ OrderByValue

การจัดเรียงและการกรองข้อมูล

คุณสามารถใช้คลาส Realtime Database Query เพื่อดึงข้อมูลที่จัดเรียงตาม คีย์ ตามค่า หรือตามค่าของข้อมูลย่อย นอกจากนี้ คุณยังกรองผลลัพธ์ที่จัดเรียงแล้วให้แสดงผลลัพธ์ตามจำนวนที่เฉพาะเจาะจง หรือตามช่วงคีย์หรือค่าที่เฉพาะเจาะจงได้ด้วย

จัดเรียงข้อมูล

หากต้องการดึงข้อมูลที่จัดเรียงแล้ว ให้เริ่มต้นด้วยการระบุวิธีการจัดเรียงอย่างใดอย่างหนึ่งเพื่อกำหนดวิธีจัดเรียงผลลัพธ์

คุณใช้เมธอดการจัดเรียงได้เพียงเมธอดเดียว ในแต่ละครั้ง การเรียกเมธอดการจัดเรียงหลายครั้งในการค้นหาเดียวกันจะทำให้เกิดข้อผิดพลาด

ตัวอย่างต่อไปนี้แสดงวิธีสมัครรับข้อมูลลีดเดอร์บอร์ดคะแนนที่จัดเรียงตามคะแนน

  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 จะซิงโครไนซ์ไคลเอ็นต์กับลีดเดอร์บอร์ด ในฐานข้อมูล โดยจัดเรียงตามคะแนนของแต่ละรายการ อ่านเพิ่มเติมเกี่ยวกับการจัดโครงสร้างข้อมูลอย่างมีประสิทธิภาพได้ที่ หัวข้อจัดโครงสร้างฐานข้อมูล

การเรียกเมธอด OrderByChild() จะระบุคีย์ย่อยที่จะใช้จัดเรียงผลลัพธ์ ในกรณีนี้ ระบบจะจัดเรียงผลลัพธ์ตามค่าของ "score" ค่าในข้อมูลย่อยแต่ละรายการ ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีจัดเรียงข้อมูลประเภทอื่นๆ ได้ที่ หัวข้อ วิธีจัดเรียงข้อมูลการค้นหา

การกรองข้อมูล

หากต้องการกรองข้อมูล คุณสามารถรวมเมธอดการจำกัดหรือเมธอดช่วงใดก็ได้กับเมธอดการจัดเรียงเมื่อสร้างการค้นหา

คุณสามารถรวมฟังก์ชันการจำกัดหรือฟังก์ชันช่วงหลายรายการได้ ซึ่งแตกต่างจากเมธอดการจัดเรียง เช่น คุณสามารถรวมเมธอด StartAt() และ EndAt() เพื่อจำกัดผลลัพธ์ให้อยู่ในช่วงค่าที่ระบุ

แม้ว่าการค้นหาจะมีผลลัพธ์ที่ตรงกันเพียงรายการเดียว สแนปชอตก็ยังคงเป็นรายการ เพียงแต่มีรายการเดียว

จำกัดจำนวนผลลัพธ์

คุณสามารถใช้เมธอด LimitToFirst() และ LimitToLast() เพื่อกำหนดจำนวนสูงสุดของข้อมูลย่อยที่จะซิงค์สำหรับการเรียกกลับที่กำหนด เช่น หากคุณใช้ LimitToFirst() เพื่อกำหนดขีดจำกัดเป็น 100 คุณจะได้รับการเรียกกลับ OnChildAdded ไม่เกิน 100 รายการในตอนแรก หากคุณมีรายการที่เก็บไว้ในฐานข้อมูล Firebase น้อยกว่า 100 รายการ ระบบจะทริกเกอร์การเรียกกลับ 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 ระบบจะจัดเรียงตามลำดับพจนานุกรมตามคีย์
3. ข้อมูลย่อยที่มีค่า true สำหรับคีย์ย่อยที่ระบุ จะแสดงถัดไป หากข้อมูลย่อยหลายรายการมีค่า true ระบบจะจัดเรียงตามลำดับพจนานุกรมตามคีย์
4. ข้อมูลย่อยที่มีค่าเป็นตัวเลขจะแสดงถัดไป โดยจัดเรียงจากน้อยไปมาก หากข้อมูลย่อยหลายรายการมีค่าตัวเลขเดียวกันสำหรับโหนดย่อยที่ระบุ ระบบจะจัดเรียงตามคีย์
5. สตริงจะแสดงหลังตัวเลขและจัดเรียงตามลำดับพจนานุกรมจากน้อยไปมาก หากข้อมูลย่อยหลายรายการมีค่าเดียวกันสำหรับโหนดย่อยที่ระบุ ระบบจะจัดเรียงตามลำดับพจนานุกรมตามคีย์
6. ออบเจ็กต์จะแสดงสุดท้ายและจัดเรียงตามลำดับพจนานุกรมตามคีย์จากน้อยไปมาก

OrderByKey

เมื่อใช้ OrderByKey() เพื่อจัดเรียงข้อมูล ระบบจะแสดงผลข้อมูลตามลำดับจากน้อยไปมากตามคีย์

1. ข้อมูลย่อยที่มีคีย์ที่แยกวิเคราะห์เป็นจำนวนเต็ม 32 บิตได้จะแสดงก่อน โดยจัดเรียงจากน้อยไปมาก
2. ข้อมูลย่อยที่มีค่าสตริงเป็นคีย์จะแสดงถัดไป โดยจัดเรียงตามลำดับพจนานุกรมจากน้อยไปมาก

OrderByValue

เมื่อใช้ OrderByValue() ระบบจะจัดเรียงข้อมูลย่อยตามค่า เกณฑ์การจัดเรียงจะเหมือนกับใน OrderByChild() ยกเว้นว่าจะใช้ค่าของโหนดแทนค่าของคีย์ย่อยที่ระบุ

ขั้นตอนถัดไป

• การบันทึกข้อมูล