กำลังดึงข้อมูล

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

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

OrderByKey

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

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

OrderByValue

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