การดึงข้อมูลด้วยฐานข้อมูลเรียลไทม์ของ Firebase สำหรับ 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 สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการตรวจสอบข้อผิดพลาด และวิธีการพิจารณาเมื่อผลลัพธ์พร้อม

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

คุณสามารถเพิ่มผู้ฟังเพื่อติดตามการเปลี่ยนแปลงข้อมูล:

คลาสพื้นฐานของ ValueListener

โทรกลับ	การใช้งานทั่วไป
OnValueChanged	อ่านและฟังการเปลี่ยนแปลงเนื้อหาทั้งหมดของเส้นทาง

คลาสพื้นฐานของ OnChildListener

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

คลาส ValueListener

คุณสามารถใช้การเรียกกลับ OnValueChanged เพื่อสมัครรับการเปลี่ยนแปลงเนื้อหาตามเส้นทางที่กำหนด การโทรกลับนี้จะถูกเรียกใช้หนึ่งครั้งเมื่อเชื่อมต่อ 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<firebase::database::DataSnapshot> result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

ผลลัพธ์ Future&ltDataSnaphot&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()	ลำดับผลลัพธ์ตามค่าลูก

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

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

  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" ในแต่ละลูก สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีจัดลำดับประเภทข้อมูลอื่นๆ โปรดดูที่ วิธีจัดลำดับข้อมูลคิวรี

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

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

วิธี	การใช้งาน
LimitToFirst()	ตั้งค่าจำนวนรายการสูงสุดที่จะส่งคืนจากจุดเริ่มต้นของรายการผลลัพธ์ที่เรียงลำดับ
LimitToLast()	ตั้งค่าจำนวนสูงสุดของรายการที่จะส่งคืนจากจุดสิ้นสุดของรายการผลลัพธ์ที่เรียงลำดับ
StartAt()	ส่งคืนรายการที่มากกว่าหรือเท่ากับคีย์หรือค่าที่ระบุโดยขึ้นอยู่กับวิธีการสั่งซื้อที่เลือก
EndAt()	ส่งคืนรายการที่น้อยกว่าหรือเท่ากับคีย์หรือค่าที่ระบุขึ้นอยู่กับวิธีการสั่งซื้อที่เลือก
EqualTo()	ส่งคืนรายการเท่ากับคีย์หรือค่าที่ระบุขึ้นอยู่กับวิธีการสั่งซื้อที่เลือก

คุณสามารถรวมฟังก์ชันจำกัดหรือช่วงได้หลายรายการ ตัวอย่างเช่น คุณสามารถรวมเมธอด 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() ยกเว้นว่าจะใช้ค่าของโหนดแทนค่าของคีย์ลูกที่ระบุ

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

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