เอกสารนี้ครอบคลุมพื้นฐานในการเรียกข้อมูล รวมถึงวิธีสั่งซื้อและกรองข้อมูล Firebase
ก่อนที่คุณจะเริ่ม
ก่อนที่คุณจะสามารถใช้ Realtime Database คุณต้อง:
ลงทะเบียนโปรเจ็กต์ Unity ของคุณและกำหนดค่าให้ใช้ Firebase
หากโปรเจ็กต์ Unity ของคุณใช้ Firebase อยู่แล้ว แสดงว่ามีการลงทะเบียนและกำหนดค่าสำหรับ Firebase แล้ว
หากคุณไม่มีโปรเจ็กต์ Unity คุณสามารถดาวน์โหลด แอปตัวอย่าง ได้
เพิ่ม Firebase Unity SDK (โดยเฉพาะ
FirebaseDatabase.unitypackage
) ให้กับโปรเจ็กต์ Unity ของคุณ
โปรดทราบว่าการเพิ่ม Firebase ให้กับโปรเจ็กต์ Unity ของคุณเกี่ยวข้องกับงานทั้งใน คอนโซล Firebase และในโปรเจ็กต์ Unity ที่เปิดอยู่ของคุณ (เช่น คุณดาวน์โหลดไฟล์การกำหนดค่า Firebase จากคอนโซล จากนั้นย้ายไฟล์เหล่านั้นไปยังโปรเจ็กต์ Unity ของคุณ)
การดึงข้อมูล
ข้อมูล Firebase จะถูกดึงข้อมูลโดยการเรียก GetValueAsync() เพียงครั้งเดียว หรือแนบกับเหตุการณ์ในการอ้างอิง FirebaseDatabase
Listener เหตุการณ์จะถูกเรียกหนึ่งครั้งสำหรับสถานะเริ่มต้นของข้อมูล และเรียกอีกครั้งทุกครั้งที่ข้อมูลมีการเปลี่ยนแปลง
รับการอ้างอิงฐานข้อมูล
หากต้องการอ่านข้อมูลจากฐานข้อมูล คุณต้องมีอินสแตนซ์ของ DatabaseReference
:
using Firebase; using Firebase.Database; using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread public class MyScript: MonoBehaviour { void Start() { // Get the root reference location of the database. DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference; } }
อ่านข้อมูลครั้งเดียว
คุณสามารถใช้เมธอด GetValueAsync
เพื่ออ่านสแนปช็อตแบบคงที่ของเนื้อหาในเส้นทางที่กำหนดเพียงครั้งเดียว ผลลัพธ์ของงานจะมีสแน็ปช็อตที่มีข้อมูลทั้งหมด ณ ตำแหน่งนั้น รวมถึงข้อมูลลูกด้วย หากไม่มีข้อมูล สแนปชอตที่ส่งคืนจะเป็น null
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .GetValueAsync().ContinueWithOnMainThread(task => { if (task.IsFaulted) { // Handle the error... } else if (task.IsCompleted) { DataSnapshot snapshot = task.Result; // Do something with snapshot... } });
ฟังเหตุการณ์
คุณสามารถเพิ่มผู้ฟังเหตุการณ์เพื่อสมัครรับการเปลี่ยนแปลงข้อมูลได้:
เหตุการณ์ | การใช้งานทั่วไป |
---|---|
ValueChanged | อ่านและฟังการเปลี่ยนแปลงเนื้อหาทั้งหมดของเส้นทาง |
ChildAdded | ดึงรายการของรายการหรือฟังการเพิ่มเติมในรายการของรายการ แนะนำให้ใช้กับ ChildChanged และ ChildRemoved เพื่อตรวจสอบการเปลี่ยนแปลงรายการ |
ChildChanged | ฟังการเปลี่ยนแปลงของรายการในรายการ ใช้กับ ChildAdded และ ChildRemoved เพื่อตรวจสอบการเปลี่ยนแปลงรายการ |
ChildRemoved | ฟังรายการที่ถูกลบออกจากรายการ ใช้กับ ChildAdded และ ChildChanged เพื่อตรวจสอบการเปลี่ยนแปลงรายการ |
ChildMoved | ฟังการเปลี่ยนแปลงลำดับของรายการในรายการสั่งซื้อ เหตุการณ์ ChildMoved มักจะเป็นไปตามเหตุการณ์ ChildChanged ที่ทำให้ลำดับของรายการเปลี่ยนแปลง (ขึ้นอยู่กับวิธีการเรียงลำดับปัจจุบันของคุณ) |
เหตุการณ์การเปลี่ยนแปลงมูลค่า
คุณสามารถใช้เหตุการณ์ ValueChanged
เพื่อสมัครรับการเปลี่ยนแปลงเนื้อหาในเส้นทางที่กำหนด เหตุการณ์นี้จะถูกทริกเกอร์หนึ่งครั้งเมื่อมีการแนบ Listener และจะเกิดขึ้นอีกครั้งทุกครั้งที่ข้อมูล รวมถึงลูกๆ มีการเปลี่ยนแปลง การเรียกกลับเหตุการณ์จะถูกส่งผ่านสแน็ปช็อตที่มีข้อมูลทั้งหมด ณ ตำแหน่งนั้น รวมถึงข้อมูลลูกด้วย หากไม่มีข้อมูล สแนปชอตที่ส่งคืนจะเป็น null
ตัวอย่างต่อไปนี้สาธิตเกมที่ดึงคะแนนของลีดเดอร์บอร์ดจากฐานข้อมูล:
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
ValueChangedEventArgs
มี DataSnapshot
ที่มีข้อมูลในตำแหน่งที่ระบุในฐานข้อมูล ณ เวลาที่เกิดเหตุการณ์ การเรียก Value
บนสแน็ปช็อตส่งคืน Dictionary<string, object>
ที่แสดงถึงข้อมูล หากไม่มีข้อมูลอยู่ที่ตำแหน่งนั้น การเรียก Value
จะส่งคืน null
ในตัวอย่างนี้ args.DatabaseError
จะถูกตรวจสอบด้วยเพื่อดูว่าการอ่านถูกยกเลิกหรือไม่ ตัวอย่างเช่น คุณสามารถยกเลิกการอ่านได้หากไคลเอ็นต์ไม่มีสิทธิ์อ่านจากตำแหน่งฐานข้อมูล Firebase DatabaseError
จะระบุว่าเหตุใดจึงเกิดความล้มเหลว
คุณสามารถยกเลิกการสมัครจากกิจกรรมได้ในภายหลังโดยใช้ DatabaseReference
ใดๆ ที่มีเส้นทางเดียวกัน อินสแตนซ์ DatabaseReference
เป็นแบบชั่วคราวและอาจถือเป็นวิธีในการเข้าถึงเส้นทางและการสืบค้นใดๆ
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged. }
กิจกรรมเด็ก
เหตุการณ์ลูกจะถูกทริกเกอร์เพื่อตอบสนองต่อการดำเนินการเฉพาะที่เกิดขึ้นกับลูกของโหนดจากการดำเนินการ เช่น ลูกใหม่ที่เพิ่มผ่านเมธอด Push()
หรือลูกที่ได้รับการอัปเดตผ่านเมธอด UpdateChildrenAsync()
แต่ละสิ่งเหล่านี้รวมกันจะมีประโยชน์สำหรับการฟังการเปลี่ยนแปลงของโหนดเฉพาะในฐานข้อมูล ตัวอย่างเช่น เกมอาจใช้วิธีการเหล่านี้ร่วมกันเพื่อติดตามกิจกรรมในความคิดเห็นของเซสชันเกม ดังที่แสดงด้านล่าง:
var ref = FirebaseDatabase.DefaultInstance .GetReference("GameSessionComments"); ref.ChildAdded += HandleChildAdded; ref.ChildChanged += HandleChildChanged; ref.ChildRemoved += HandleChildRemoved; ref.ChildMoved += HandleChildMoved; } void HandleChildAdded(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildChanged(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildRemoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot } void HandleChildMoved(object sender, ChildChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
โดยทั่วไปเหตุการณ์ ChildAdded
จะใช้เพื่อดึงข้อมูลรายการในฐานข้อมูล Firebase เหตุการณ์ ChildAdded
จะถูกยกขึ้นหนึ่งครั้งสำหรับแต่ละลูกที่มีอยู่ และอีกครั้งทุกครั้งที่มีการเพิ่มลูกใหม่ในเส้นทางที่ระบุ ผู้ฟังจะถูกส่งผ่านสแน็ปช็อตที่มีข้อมูลของเด็กใหม่
เหตุการณ์ ChildChanged
จะเกิดขึ้นทุกครั้งที่มีการแก้ไขโหนดลูก ซึ่งรวมถึงการปรับเปลี่ยนใด ๆ กับการสืบทอดของโหนดลูก โดยทั่วไปจะใช้ร่วมกับเหตุการณ์ ChildAdded
และ ChildRemoved
เพื่อตอบสนองต่อการเปลี่ยนแปลงรายการต่างๆ สแน็ปช็อตที่ส่งไปยังตัวฟังเหตุการณ์ประกอบด้วยข้อมูลที่อัปเดตสำหรับเด็ก
เหตุการณ์ ChildRemoved
จะถูกทริกเกอร์เมื่อมีการลบรายการย่อยทันที โดยทั่วไปจะใช้ร่วมกับการโทรกลับ ChildAdded
และ ChildChanged
สแน็ปช็อตที่ส่งไปยังการเรียกกลับเหตุการณ์ประกอบด้วยข้อมูลสำหรับเด็กที่ถูกลบออก
เหตุการณ์ ChildMoved
จะถูกทริกเกอร์เมื่อใดก็ตามที่เหตุการณ์ ChildChanged
เกิดขึ้นจากการอัปเดตที่ทำให้เกิดการเรียงลำดับของเด็กใหม่ ใช้กับข้อมูลที่เรียงลำดับด้วย OrderByChild
หรือ OrderByValue
การเรียงลำดับและการกรองข้อมูล
คุณสามารถใช้คลาส Realtime Database Query
เพื่อดึงข้อมูลที่จัดเรียงตามคีย์ ตามค่า หรือตามค่าของรายการย่อย คุณยังสามารถกรองผลลัพธ์ที่จัดเรียงตามจำนวนผลลัพธ์หรือช่วงของคีย์หรือค่าที่ต้องการได้
จัดเรียงข้อมูล
หากต้องการดึงข้อมูลที่เรียงลำดับ ให้เริ่มต้นด้วยการระบุวิธีเรียงลำดับตามวิธีใดวิธีหนึ่งเพื่อกำหนดวิธีเรียงลำดับผลลัพธ์:
วิธี | การใช้งาน |
---|---|
OrderByChild() | เรียงลำดับผลลัพธ์ตามค่าของคีย์ลูกที่ระบุ | OrderByKey() | เรียงลำดับผลลัพธ์ด้วยคีย์ลูก |
OrderByValue() | เรียงลำดับผลลัพธ์ตามค่าลูก |
คุณสามารถใช้วิธีสั่งซื้อได้ครั้งละ หนึ่ง วิธีเท่านั้น การเรียกวิธีการเรียงลำดับหลายครั้งในแบบสอบถามเดียวกันทำให้เกิดข้อผิดพลาด
ตัวอย่างต่อไปนี้สาธิตวิธีการสมัครรับข้อมูลกระดานผู้นำคะแนนโดยเรียงตามคะแนน
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score") .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
สิ่งนี้กำหนดการสืบค้นที่เมื่อรวมกับ ตัวฟังเหตุการณ์ที่เปลี่ยนแปลงมูลค่า จะซิงโครไนซ์ไคลเอนต์กับกระดานผู้นำในฐานข้อมูล โดยเรียงลำดับตามคะแนนของแต่ละรายการ คุณสามารถอ่านเพิ่มเติมเกี่ยวกับการจัดโครงสร้างข้อมูลของคุณอย่างมีประสิทธิภาพได้ใน โครงสร้างฐานข้อมูลของคุณ
การเรียกเมธอด OrderByChild()
ระบุคีย์ลูกเพื่อเรียงลำดับผลลัพธ์ตาม ในกรณีนี้ ผลลัพธ์จะถูกจัดเรียงตามค่าของค่า "score"
ในแต่ละรายการย่อย สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการเรียงลำดับข้อมูลประเภทอื่นๆ โปรดดู วิธีการเรียงลำดับข้อมูลคิวรี
การกรองข้อมูล
หากต้องการกรองข้อมูล คุณสามารถรวมวิธีการจำกัดหรือช่วงใดๆ เข้ากับวิธีเรียงลำดับตามเมื่อสร้างแบบสอบถามได้
วิธี | การใช้งาน |
---|---|
LimitToFirst() | ตั้งค่าจำนวนรายการสูงสุดที่จะส่งคืนจากจุดเริ่มต้นของรายการผลลัพธ์ที่เรียงลำดับ |
LimitToLast() | ตั้งค่าจำนวนรายการสูงสุดที่จะส่งคืนจากจุดสิ้นสุดของรายการผลลัพธ์ที่เรียงลำดับ |
StartAt() | ส่งคืนรายการที่มากกว่าหรือเท่ากับคีย์หรือค่าที่ระบุ ขึ้นอยู่กับวิธีการเรียงลำดับที่เลือก |
EndAt() | ส่งคืนรายการที่น้อยกว่าหรือเท่ากับคีย์หรือค่าที่ระบุ ขึ้นอยู่กับวิธีการเรียงลำดับที่เลือก |
EqualTo() | ส่งคืนสินค้าเท่ากับคีย์หรือค่าที่ระบุ ขึ้นอยู่กับวิธีการเรียงลำดับที่เลือก |
ต่างจากวิธีการเรียงลำดับตาม คุณสามารถรวมฟังก์ชันขีดจำกัดหรือช่วงหลายรายการเข้าด้วยกันได้ ตัวอย่างเช่น คุณสามารถรวมเมธอด StartAt()
และ EndAt()
เพื่อจำกัดผลลัพธ์ให้อยู่ในช่วงของค่าที่ระบุ
แม้ว่าจะมีการจับคู่การค้นหาเพียงรายการเดียว สแน็ปช็อตก็ยังคงเป็นรายการ มันมีรายการเดียว
จำกัดจำนวนผลลัพธ์
คุณสามารถใช้เมธอด LimitToFirst()
และ LimitToLast()
เพื่อตั้งค่าจำนวนลูกสูงสุดที่จะซิงค์สำหรับการโทรกลับที่ระบุ ตัวอย่างเช่น หากคุณใช้ LimitToFirst()
เพื่อกำหนดขีดจำกัดไว้ที่ 100 ในตอนแรกคุณจะได้รับการโทรกลับ ChildAdded
สูงสุด 100 รายการเท่านั้น หากคุณมีรายการเก็บไว้ในฐานข้อมูล Firebase น้อยกว่า 100 รายการ ระบบเรียกกลับ ChildAdded
จะเริ่มทำงานสำหรับแต่ละรายการ
เมื่อรายการเปลี่ยนแปลง คุณจะได้รับการโทรกลับ ChildAdded
สำหรับรายการที่ป้อนแบบสอบถามและการเรียกกลับ ChildRemoved
สำหรับรายการที่หลุดออกไป เพื่อให้จำนวนรวมอยู่ที่ 100
ตัวอย่างเช่น โค้ดด้านล่างส่งคืนคะแนนสูงสุดจากลีดเดอร์บอร์ด:
FirebaseDatabase.DefaultInstance .GetReference("Leaders").OrderByChild("score").LimitToLast(1) .ValueChanged += HandleValueChanged; } void HandleValueChanged(object sender, ValueChangedEventArgs args) { if (args.DatabaseError != null) { Debug.LogError(args.DatabaseError.Message); return; } // Do something with the data in args.Snapshot }
กรองตามคีย์หรือค่า
คุณสามารถใช้ StartAt()
, EndAt()
และ EqualTo()
เพื่อเลือกจุดเริ่มต้น จุดสิ้นสุด และจุดเทียบเท่าสำหรับการสืบค้นได้ตามต้องการ สิ่งนี้มีประโยชน์สำหรับการแบ่งหน้าข้อมูลหรือค้นหารายการที่มีรายการลูกที่มีค่าเฉพาะ
วิธีเรียงลำดับข้อมูลการสืบค้น
ในส่วนนี้จะอธิบายวิธีการจัดเรียงข้อมูลตามวิธีเรียงลำดับตามแต่ละวิธีในคลาส Query
OrderByChild
เมื่อใช้ OrderByChild()
ข้อมูลที่มีคีย์ลูกที่ระบุจะถูกเรียงลำดับดังนี้:
- รายการย่อยที่มีค่า
null
สำหรับคีย์ลูกที่ระบุจะต้องมาก่อน - รายการย่อยที่มีค่า
false
สำหรับคีย์ลูกที่ระบุจะอยู่ลำดับถัดไป หากลูกหลายคนมีค่าเป็นfalse
พวกเขาจะถูกจัดเรียงตาม พจนานุกรม ตามคีย์ - รายการย่อยที่มีค่า
true
สำหรับรหัสลูกที่ระบุจะอยู่ลำดับถัดไป หากรายการย่อยหลายรายการมีค่าเป็นtrue
รายการเหล่านั้นจะถูกจัดเรียงตามพจนานุกรมตามคีย์ - ลูกที่มีค่าตัวเลขจะมาถัดไป เรียงลำดับจากน้อยไปหามาก ถ้าลูกหลายคนมีค่าตัวเลขเหมือนกันสำหรับโหนดลูกที่ระบุ พวกเขาจะถูกจัดเรียงตามคีย์
- สตริงจะอยู่หลังตัวเลข และจัดเรียงตามพจนานุกรมจากน้อยไปหามาก หากลูกหลายคนมีค่าเดียวกันสำหรับโหนดลูกที่ระบุ พวกเขาจะถูกเรียงลำดับตามพจนานุกรมตามคีย์
- วัตถุจะอยู่ลำดับสุดท้ายและจัดเรียงตามพจนานุกรมตามคีย์จากน้อยไปหามาก
OrderByKey
เมื่อใช้ OrderByKey()
เพื่อจัดเรียงข้อมูลของคุณ ข้อมูลจะถูกส่งกลับโดยเรียงจากน้อยไปมากตามคีย์
- รายการย่อยที่มีคีย์ที่สามารถแยกวิเคราะห์เป็นจำนวนเต็ม 32 บิตมาก่อน โดยเรียงลำดับจากน้อยไปหามาก
- รายการย่อยที่มีค่าสตริงเป็นคีย์จะอยู่ลำดับถัดไป โดยเรียงลำดับตามพจนานุกรมจากน้อยไปหามาก
OrderByValue
เมื่อใช้ OrderByValue()
ลูกจะถูกเรียงลำดับตามค่าของพวกเขา เกณฑ์การเรียงลำดับจะเหมือนกับใน OrderByChild()
ยกเว้นว่าจะใช้ค่าของโหนดแทนค่าของคีย์ลูกที่ระบุ