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

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

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

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

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

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

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

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

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

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

วิธีการ	การใช้งาน
`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 ซึ่งเมื่อใช้ร่วมกับ a 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() ระบบจะจัดลำดับข้อมูลที่มีคีย์ย่อยที่ระบุดังนี้

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

`OrderByKey`

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

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

`OrderByValue`

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

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

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