หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

ลงทะเบียนโปรเจ็กต์ Unity และกําหนดค่าให้ใช้ Firebase
- หากโปรเจ็กต์ Unity ใช้ Firebase อยู่แล้ว ก็แสดงว่าได้ ลงทะเบียนและกำหนดค่าสำหรับ Firebase แล้ว
- หากไม่มีโปรเจ็กต์ Unity คุณสามารถดาวน์โหลดแอปตัวอย่างได้
เพิ่ม Firebase Unity SDK (โดยเฉพาะ FirebaseDatabase.unitypackage) ลงใน โปรเจ็กต์ Unity

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

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

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

หมายเหตุ: โดยค่าเริ่มต้น ระบบจะจำกัดสิทธิ์อ่านและเขียนในฐานข้อมูลของคุณเพื่อให้เฉพาะ ผู้ใช้ที่ผ่านการตรวจสอบสิทธิ์เท่านั้นที่อ่านหรือเขียนข้อมูลได้ หากต้องการเริ่มต้นใช้งานโดยไม่ต้องตั้งค่า Authentication คุณสามารถกำหนดค่านโยบายสำหรับการเข้าถึงแบบสาธารณะได้ การดำเนินการนี้จะ ทำให้ทุกคนเข้าถึงฐานข้อมูลของคุณได้ แม้แต่ผู้ที่ไม่ได้ใช้แอปของคุณ ดังนั้น อย่าลืมจำกัดฐานข้อมูลอีกครั้งเมื่อตั้งค่าการตรวจสอบสิทธิ์

รับ 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

สำคัญ: ระบบจะเรียกใช้เหตุการณ์ ValueChanged ทุกครั้งที่มีการเปลี่ยนแปลงข้อมูลที่ การอ้างอิงฐานข้อมูลที่ระบุ รวมถึงการเปลี่ยนแปลงในรายการย่อย หากต้องการจำกัด ขนาดของสแนปชอต ให้แนบเฉพาะที่ระดับสูงสุดที่จำเป็นสำหรับการดู การเปลี่ยนแปลง เช่น ไม่แนะนําให้แนบเครื่องมือฟังเหตุการณ์กับรูทของฐานข้อมูล

ตัวอย่างต่อไปนี้แสดงเกมที่ดึงคะแนนของลีดเดอร์บอร์ดจากฐานข้อมูล

      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.
    }

กิจกรรมย่อย

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

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

`OrderByKey`

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

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

`OrderByValue`

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