เอกสารนี้ครอบคลุมพื้นฐานการดึงข้อมูลและวิธีสั่งซื้อและกรองข้อมูล 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<DataSnaphot>
มีข้อมูลในตำแหน่งที่ระบุในฐานข้อมูล ณ เวลาที่เกิดเหตุการณ์ 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()
ข้อมูลที่มีรหัสลูกที่ระบุจะถูกเรียงลำดับดังนี้:
- ลูกที่มีค่า
null
สำหรับคีย์ลูกที่ระบุมาก่อน - ลูกที่มีค่าเป็น
false
สำหรับคีย์ลูกที่ระบุจะอยู่ถัดไป หากเด็กหลายคนมีค่าเป็นfalse
พวกเขาจะถูกจัดเรียงตาม พจนานุกรม ตามคีย์ - ลูกที่มีค่า
true
สำหรับคีย์ลูกที่ระบุจะอยู่ถัดไป หากลูกหลายคนมีค่าเป็นtrue
จะมีการจัดเรียงตามพจนานุกรมตามคีย์ - เด็กที่มีค่าตัวเลขมาถัดไป เรียงลำดับจากน้อยไปหามาก ถ้าโหนดย่อยหลายโหนดมีค่าตัวเลขเดียวกันสำหรับโหนดย่อยที่ระบุ พวกเขาจะถูกจัดเรียงตามคีย์
- สตริงมาหลังตัวเลขและจัดเรียงตามพจนานุกรมจากน้อยไปหามาก หากโหนดย่อยหลายรายการมีค่าเท่ากันสำหรับโหนดย่อยที่ระบุ ระบบจะเรียงลำดับตามพจนานุกรมตามคีย์
- ออบเจกต์จะอยู่หลังสุดและจัดเรียงตามพจนานุกรมตามคีย์ในลำดับจากน้อยไปหามาก
OrderByKey
เมื่อใช้ OrderByKey()
เพื่อจัดเรียงข้อมูล ข้อมูลจะถูกส่งกลับตามลำดับคีย์
- เด็กที่มีคีย์ที่สามารถแยกวิเคราะห์เป็นจำนวนเต็ม 32 บิตมาก่อน เรียงลำดับจากน้อยไปหามาก
- เด็กที่มีค่าสตริงเป็นคีย์อยู่ถัดไป จัดเรียงตามพจนานุกรมจากน้อยไปหามาก
OrderByValue
เมื่อใช้ OrderByValue()
เด็กจะเรียงลำดับตามมูลค่า เกณฑ์การสั่งซื้อจะเหมือนกับใน OrderByChild()
ยกเว้นว่าจะใช้ค่าของโหนดแทนค่าของคีย์ลูกที่ระบุ