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

เอกสารนี้ครอบคลุมพื้นฐานของการดึงข้อมูล รวมถึงวิธีจัดเรียงและกรองข้อมูล Firebase

ก่อนเริ่มต้น

คุณต้องดำเนินการต่อไปนี้ก่อนจึงจะใช้ Realtime Database ได้

  • ลงทะเบียนโปรเจ็กต์ Unity และกําหนดค่าให้ใช้ Firebase

    • หากโปรเจ็กต์ Unity ใช้ Firebase อยู่แล้ว ก็แสดงว่าได้ ลงทะเบียนและกำหนดค่าสำหรับ Firebase แล้ว

    • หากไม่มีโปรเจ็กต์ Unity คุณสามารถดาวน์โหลดแอปตัวอย่างได้

  • เพิ่ม Firebase Unity SDK (โดยเฉพาะ FirebaseDatabase.unitypackage) ลงใน โปรเจ็กต์ Unity

โปรดทราบว่าการเพิ่ม Firebase ลงในโปรเจ็กต์ Unity จะเกี่ยวข้องกับงานทั้งในFirebaseคอนโซลและในโปรเจ็กต์ Unity ที่เปิดอยู่ (เช่น คุณดาวน์โหลดไฟล์กำหนดค่า Firebase จากคอนโซล จากนั้นย้าย ไฟล์เหล่านั้นไปยังโปรเจ็กต์ Unity)

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

ระบบจะเรียกข้อมูล Firebase โดยการเรียก GetValueAsync() เพียงครั้งเดียวหรือ แนบกับเหตุการณ์ในFirebaseDatabaseการอ้างอิง ระบบจะเรียกใช้เครื่องมือฟังเหตุการณ์ หนึ่งครั้งสำหรับสถานะเริ่มต้นของข้อมูล และอีกครั้งเมื่อใดก็ตามที่ข้อมูลเปลี่ยนแปลง

รับ DatabaseReference

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

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task =&gt {
        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

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

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

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

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

คุณใช้วิธีการจัดเรียงได้วิธีเดียวในแต่ละครั้ง การเรียกใช้เมธอด Order-by หลายครั้งในคำค้นหาเดียวกันจะทำให้เกิดข้อผิดพลาด

ตัวอย่างต่อไปนี้แสดงวิธีที่คุณจะติดตามในลีดเดอร์บอร์ดคะแนนที่จัดเรียงตามคะแนนได้ 

      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
    }

ซึ่งจะกําหนดคําค้นหาที่เมื่อรวมกับเครื่องมือฟังเหตุการณ์ valuechanged จะซิงค์ไคลเอ็นต์กับลีดเดอร์บอร์ดในฐานข้อมูล โดยเรียงตามคะแนนของแต่ละรายการ คุณอ่านเพิ่มเติมเกี่ยวกับการจัดโครงสร้างข้อมูลอย่างมีประสิทธิภาพได้ในจัดโครงสร้างฐานข้อมูล

การเรียกใช้เมธอด OrderByChild() จะระบุคีย์ย่อยเพื่อจัดเรียง ผลลัพธ์ ในกรณีนี้ ระบบจะจัดเรียงผลลัพธ์ตามค่าของ "score" ค่าในแต่ละรายการย่อย ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีจัดเรียงข้อมูลประเภทอื่นๆ ได้ที่วิธีจัดเรียงข้อมูลการค้นหา

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

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

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

คุณรวมฟังก์ชัน limit หรือ range หลายรายการได้ ซึ่งต่างจากเมธอด order-by เช่น คุณสามารถรวมเมธอด 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() ยกเว้นจะใช้ค่าของโหนดแทนค่าของคีย์ย่อยที่ ระบุ