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

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

คุณเพิ่ม Listener เพื่อติดตามการเปลี่ยนแปลงของข้อมูลได้โดยทำดังนี้

คลาสฐาน ValueListener

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

คลาสฐาน OnChildListener

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

คลาส ValueListener

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

ผลลัพธ์ Future&ltDataSnapshot&gt มีข้อมูลในตำแหน่งที่ระบุ ในฐานข้อมูล ณ เวลาที่เกิดเหตุการณ์ กำลังโทรหา value() บนสแนปชอต แสดงผล Variant ที่แสดงถึงข้อมูล

ในตัวอย่างนี้ เมธอด OnCancelled จะถูกลบล้างเพื่อดูว่ามีการอ่าน ถูกยกเลิก ตัวอย่างเช่น การอ่านอาจถูกยกเลิกหากลูกค้าไม่มี สิทธิ์ในการอ่านจากตำแหน่งฐานข้อมูล Firebase database::Error จะ ระบุสาเหตุของความล้มเหลว

คลาส ChildListener

ระบบจะทริกเกอร์เหตุการณ์ย่อยเพื่อตอบสนองต่อการดำเนินการบางอย่างที่เกิดขึ้นกับ ย่อยของโหนดจากการดำเนินการ เช่น รายการย่อยใหม่ที่เพิ่มผ่าน เมธอด PushChild() หรือย่อยที่ได้รับการอัปเดตผ่าน UpdateChildren() การใช้ทั้ง 2 อย่างนี้ร่วมกันจะเป็นประโยชน์ต่อการตอบสนองต่อการเปลี่ยนแปลงของ ในฐานข้อมูล ตัวอย่างเช่น เกมอาจใช้วิธีการเหล่านี้ ร่วมกันเพื่อตรวจสอบกิจกรรมในความคิดเห็นของเซสชันเกม ตามที่ปรากฏด้านล่าง:

  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);

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

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

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

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

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

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

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

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

วิธีการ การใช้งาน
OrderByChild() เรียงลำดับผลลัพธ์ตามค่าของคีย์ย่อยที่ระบุ
OrderByKey() เรียงลำดับผลการค้นหาตามคีย์ย่อย
OrderByValue() เรียงลำดับผลลัพธ์ตามค่าย่อย

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

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

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

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

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

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

จำกัดจำนวนผลการค้นหา

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

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