การเรียกข้อมูลด้วยฐานข้อมูลเรียลไทม์ของ 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();

อ่านข้อมูลเพียงครั้งเดียว

คุณใช้เมธอด 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

คุณสามารถใช้ Callback OnValueChanged เพื่อสมัครรับข้อมูลการเปลี่ยนแปลงเนื้อหาในเส้นทางที่ระบุ ระบบจะทริกเกอร์ Callback นี้ 1 ครั้งเมื่อแนบ Listener และอีกครั้งทุกครั้งที่ข้อมูล รวมถึงข้อมูลย่อย มีการเปลี่ยนแปลง ระบบจะส่งสแนปชอตที่มีข้อมูลทั้งหมดในตำแหน่งนั้น รวมถึงข้อมูลย่อยไปยัง Callback หากไม่มีข้อมูล ภาพรวมที่แสดงผลจะเป็น 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);

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

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

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

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

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

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

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

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

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

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

  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 ในตอนแรกคุณจะได้รับ Callback ของ OnChildAdded สูงสุดเพียง 100 รายการเท่านั้น หากคุณมีรายการที่จัดเก็บไว้ในฐานข้อมูล Firebase น้อยกว่า 100 รายการ ระบบจะเรียกใช้ Callback OnChildAdded สำหรับแต่ละรายการ

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

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

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