Produk Kasus Penggunaan Harga Dokumen Bantuan
Buka konsol

Mengambil Data

Dokumen ini mencakup dasar-dasar pengambilan data serta cara mengurutkan dan memfilter data Firebase.

Sebelum memulai

Sebelum dapat menggunakan Realtime Database, Anda perlu:

  • Mendaftarkan project Unity Anda dan mengonfigurasikannya untuk menggunakan Firebase.

    • Jika project Unity Anda telah menggunakan Firebase, berarti project tersebut telah terdaftar dan dikonfigurasikan untuk Firebase.

    • Jika belum memiliki project Unity, Anda dapat mendownload aplikasi contoh.

  • Menambahkan Firebase Unity SDK (khususnya, FirebaseDatabase.unitypackage) ke project Unity Anda.

Perlu diperhatikan bahwa menambahkan Firebase ke project Unity Anda melibatkan tugas di Firebase console dan di project Unity yang terbuka (misalnya, Anda mendownload file konfigurasi Firebase dari konsol, lalu memindahkannya ke project Unity).

Mengambil Data

Data Firebase diambil dengan panggilan 1 kali untuk GetValueAsync() atau disertakan ke peristiwa pada referensi FirebaseDatabase. Listener peristiwa akan dipanggil 1 kali untuk mengetahui status awal data, dan dipanggil lagi setiap kali data berubah.

Mendapatkan DatabaseReference

Untuk membaca data dari database, Anda perlu instance DatabaseReference:

using Firebase;
using Firebase.Database;
using Firebase.Unity.Editor;

public class MyScript: MonoBehaviour {
  void Start() {
    // Set up the Editor before calling into the realtime database.
    FirebaseApp.DefaultInstance.SetEditorDatabaseUrl("https://YOUR-FIREBASE-APP.firebaseio.com/");

    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Membaca data sekali

Anda bisa menggunakan metode GetValueAsync untuk membaca snapshot statis konten di lokasi tertentu 1 kali. Hasil tugas akan berisi snapshot yang berisi semua data di lokasi tersebut, termasuk data turunan. Jika tidak ada data, snapshot yang ditampilkan adalah null.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWith(task =&gt {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Mendeteksi peristiwa

Anda dapat menambahkan listener peristiwa untuk berlangganan perubahan data:

Peristiwa Penggunaan standar
ValueChanged Membaca dan mendeteksi perubahan di seluruh konten lokasi.
ChildAdded Mengambil daftar item atau mendeteksi penambahan daftar item. Disarankan untuk digunakan dengan ChildChanged dan ChildRemoved untuk memantau perubahan daftar.
ChildChanged Mendeteksi perubahan pada item dalam daftar. Gunakan dengan ChildAdded dan ChildRemoved untuk memantau perubahan daftar.
ChildRemoved Mendeteksi item yang sedang dihapus dari daftar. Gunakan dengan ChildAdded dan ChildChanged untuk memantau perubahan daftar.
ChildMoved Mendeteksi perubahan pada urutan item dalam urutan daftar. Peristiwa ChildMoved selalu mengikuti peristiwa ChildChanged, yang menyebabkan urutan item berubah (berdasarkan metode 'urutkan berdasarkan' saat ini).

Peristiwa ValueChanged

Anda bisa menggunakan peristiwa ValueChanged untuk berlangganan perubahan konten di lokasi tertentu. Peristiwa ini dipicu 1 kali ketika listener dipasang dan dipicu lagi setiap kali terjadi perubahan data, termasuk turunannya. Peristiwa callback meneruskan snapshot yang berisi semua data di lokasi tersebut, termasuk data turunan. Jika tidak ada data, snapshot yang ditampilkan adalah null.

Contoh berikut menunjukkan game yang mengambil skor di papan peringkat dari database:

      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 berisi DataSnapshot yang memuat data di lokasi yang ditentukan dalam database pada saat peristiwa terjadi. Memanggil Value pada snapshot akan menampilkan Dictionary<string, object> yang mewakili data. Jika data tidak ada di lokasi, pemanggilan Value akan menampilkan null.

Dalam contoh ini, args.DatabaseError juga diperiksa untuk mengetahui apakah pembacaan dibatalkan atau tidak. Misalnya, proses baca bisa dibatalkan jika klien tidak memiliki izin untuk membaca dari lokasi database Firebase. DatabaseError akan menunjukkan mengapa kegagalan terjadi.

Selanjutnya, Anda dapat berhenti berlangganan peristiwa menggunakan DatabaseReference yang memiliki lokasi yang sama. Instance DatabaseReference bersifat sementara dan dapat dianggap sebagai cara untuk mengakses lokasi dan kueri apa pun.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

Peristiwa turunan

Peristiwa turunan dipicu sebagai respons terhadap operasi tertentu yang terjadi pada turunan node dari suatu operasi, seperti turunan baru yang ditambahkan melalui metode Push() atau turunan yang sedang diupdate melalui metode UpdateChildrenAsync(). Secara bersama-sama, setiap metode ini dapat berguna untuk mendeteksi perubahan terhadap node tertentu dalam database. Misalnya, suatu game mungkin menggunakan metode ini secara bersamaan untuk memantau aktivitas dalam komentar sesi game, seperti yang ditunjukkan di bawah ini:

      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
    }

Peristiwa ChildAdded biasanya digunakan untuk mengambil daftar item di database Firebase. Peristiwa ChildAdded dipicu 1 kali untuk setiap turunan yang ada, dan dipicu lagi setiap kali ada turunan baru yang ditambahkan ke lokasi yang ditetapkan. Listener meneruskan snapshot yang berisi data turunan baru.

Peristiwa ChildChanged dimunculkan setiap kali node turunan diubah. Ini juga termasuk perubahan keturunan dari node turunan. Peristiwa ini biasanya digunakan bersamaan dengan peristiwa ChildAdded dan ChildRemoved untuk menanggapi perubahan daftar item. Snapshot yang diteruskan ke listener peristiwa berisi data turunan yang diupdate.

Peristiwa ChildRemoved dipicu ketika data turunan langsung dihapus. Peristiwa ini biasanya digunakan bersamaan dengan callback ChildAdded dan ChildChanged. Snapshot yang diteruskan ke callback peristiwa berisi data untuk turunan yang dihapus.

Peristiwa ChildMoved dipicu setiap kali peristiwa ChildChanged dimunculkan oleh update yang menyebabkan pengurutan ulang turunan. Peristiwa ini digunakan dengan data yang diurutkan dengan OrderByChild atau OrderByValue.

Mengurutkan dan memfilter data

Anda bisa menggunakan class Query Realtime Database untuk memperoleh data yang diurutkan berdasarkan kunci, nilai, atau nilai turunan. Anda juga dapat memfilter hasil pengurutan ke jumlah hasil tertentu atau ke rentang kunci atau nilai.

Mengurutkan data

Untuk mengambil data yang diurutkan, mulai dengan menentukan salah satu metode 'urutkan berdasarkan' untuk menentukan cara pengurutan hasil.

Metode Penggunaan
OrderByChild() Mengurutkan hasil berdasarkan nilai kunci turunan tertentu.
OrderByKey() Mengurutkan hasil berdasarkan kunci turunan.
OrderByValue() Mengurutkan hasil berdasarkan nilai turunan.

Anda hanya bisa menggunakan 1 metode 'urutkan berdasarkan' pada satu waktu. Memanggil metode 'urutkan berdasarkan' beberapa kali dalam kueri yang sama akan menghasilkan error.

Contoh berikut menunjukkan bagaimana Anda bisa berlangganan papan peringkat skor yang diurutkan berdasarkan skor.

      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
    }

Ini menentukan kueri yang jika dikombinasikan dengan listener peristiwa valuechanged akan menyinkronkan klien dengan papan peringkat dalam database, diurutkan berdasarkan skor setiap entri. Anda dapat membaca selengkapnya tentang penyusunan struktur data secara efisien di bagian Membuat Struktur Database Anda.

Panggilan ke metode OrderByChild() menetapkan kunci turunan sebagai dasar untuk mengurutkan hasil. Dalam kasus ini, hasil diurutkan berdasarkan nilai "score" dalam setiap turunan. Untuk mengetahui informasi lebih lanjut mengenai cara pengurutan jenis data lain, baca Cara data kueri diurutkan.

Memfilter data

Untuk memfilter data, Anda dapat menggabungkan salah satu metode batas atau rentang dengan metode 'urutkan berdasarkan' ketika menyusun kueri.

Metode Penggunaan
LimitToFirst() Menetapkan jumlah item maksimum untuk ditampilkan dari awal daftar hasil yang diurutkan.
LimitToLast() Menetapkan jumlah item maksimum untuk ditampilkan dari akhir daftar hasil yang diurutkan.
StartAt() Menampilkan item yang lebih besar atau sama dengan kunci atau nilai yang ditentukan, tergantung metode 'urutkan berdasarkan' yang dipilih.
EndAt() Menampilkan item yang lebih kecil atau sama dengan kunci atau nilai yang ditentukan, tergantung metode 'urutkan berdasarkan' yang dipilih.
EqualTo() Menampilkan item yang sama dengan kunci atau nilai yang ditentukan, tergantung metode 'urutkan berdasarkan' yang dipilih.

Berbeda dengan metode 'urutkan berdasarkan', Anda dapat menggabungkan fungsi batas atau rentang. Misalnya, Anda dapat menggabungkan metode StartAt() dan EndAt() untuk membatasi hasil terhadap rentang nilai tertentu.

Meskipun jika hanya ada 1 kueri yang cocok, snapshot tetaplah sebuah daftar yang hanya berisi 1 item.

Membatasi jumlah hasil

Anda dapat menggunakan metode LimitToFirst() dan LimitToLast() untuk menetapkan jumlah maksimum turunan yang akan disinkronkan untuk callback tertentu. Misalnya, jika Anda menggunakan LimitToFirst() untuk menetapkan batas 100, pada awalnya Anda hanya akan menerima hingga 100 callback ChildAdded. Jika Anda memiliki kurang dari 100 item yang disimpan dalam database Firebase, callback ChildAdded akan dikeluarkan untuk setiap item.

Saat item berubah, Anda menerima callback ChildAdded untuk item yang masuk ke kueri dan callback ChildRemoved untuk item yang keluar, sehingga jumlah totalnya tetap 100.

Misalnya, kode berikut menampilkan skor teratas dari papan peringkat:

      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
    }

Memfilter berdasarkan kunci atau nilai

Anda dapat menggunakan StartAt(), EndAt(), dan EqualTo() untuk memilih titik awal, akhir, dan ekuivalen yang arbitrer untuk kueri. Hal ini dapat bermanfaat untuk pemberian nomor data atau menemukan item dengan turunan yang memiliki nilai tertentu.

Cara data kueri diurutkan

Bagian ini menjelaskan cara data diurutkan menggunakan setiap metode 'urutkan berdasarkan' di kelas Query.

OrderByChild

Ketika menggunakan OrderByChild(), data yang berisi kunci turunan yang ditentukan diurutkan sebagai berikut:

  1. Turunan yang memiliki nilai null untuk kunci turunan yang ditentukan akan muncul pertama.
  2. Turunan yang memiliki nilai false untuk kunci turunan yang ditentukan akan muncul berikutnya. Jika beberapa turunan memiliki nilai false, turunan tersebut akan diurutkan secara leksikografis berdasarkan kunci.
  3. Turunan yang memiliki nilai true untuk kunci turunan yang ditentukan akan muncul berikutnya. Jika beberapa turunan memiliki nilai true, turunan tersebut akan diurutkan secara leksikografis berdasarkan kunci.
  4. Turunan dengan nilai numerik akan muncul berikutnya, dan diurutkan dalam urutan menaik. Jika beberapa turunan memiliki nilai numerik yang sama untuk node turunan yang ditentukan, turunan tersebut akan diurutkan berdasarkan kunci.
  5. String muncul setelah angka, dan diurutkan secara leksikografis dalam urutan menaik. Jika beberapa turunan memiliki nilai yang sama untuk node turunan yang ditentukan, turunan tersebut akan diurutkan secara leksikografis berdasarkan kunci.
  6. Objek muncul terakhir, dan diurutkan secara leksikografis berdasarkan kunci dalam urutan menaik.

OrderByKey

Ketika menggunakan OrderByKey() untuk mengurutkan data, data akan ditampilkan dalam urutan menaik berdasarkan kunci.

  1. Turunan dengan kunci yang bisa diurai sebagai bilangan bulat 32-bit berada di urutan atas, dan diurutkan dalam urutan menaik.
  2. Turunan dengan nilai string sebagai kuncinya berada di urutan berikutnya, dan diurutkan secara leksikografis dalam urutan menaik.

OrderByValue

Ketika menggunakan OrderByValue(), turunan akan diurutkan berdasarkan nilainya. Kriteria urutan sama seperti di OrderByChild(), perbedaannya yaitu yang digunakan adalah nilai node, bukan nilai kunci turunan yang ditentukan.