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.
Tambahkan Firebase Unity SDK (khususnya, FirebaseDatabase.unitypackage) ke project Unity Anda.

Temukan petunjuk mendetail seputar tugas penyiapan awal ini di artikel Menambahkan Firebase 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 dapat menggunakan metode GetValueAsync untuk membaca snapshot statis konten di jalur tertentu sekali. 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 => {
        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 memproses perubahan di seluruh konten jalur.
`ChildAdded`	Mengambil daftar item atau memproses penambahan daftar item. Disarankan untuk digunakan dengan `ChildChanged` dan `ChildRemoved` untuk memantau perubahan daftar.
`ChildChanged`	Memproses perubahan pada item dalam daftar. Gunakan dengan `ChildAdded` dan `ChildRemoved` untuk memantau perubahan daftar.
`ChildRemoved`	Memproses item yang dihapus dari daftar. Gunakan dengan `ChildAdded` dan `ChildChanged` untuk memantau perubahan daftar.
`ChildMoved`	Mendeteksi perubahan urutan item dalam daftar terurut. Peristiwa `ChildMoved` selalu mengikuti peristiwa `ChildChanged`, yang menyebabkan urutan item berubah (berdasarkan metode 'urutkan berdasarkan' saat ini).

Peristiwa ValueChanged

Anda dapat 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. Pemanggilan Value pada snapshot akan menampilkan Dictionary<string, object> yang mewakili data tersebut. Jika tidak ada data di lokasi, null akan ditampilkan saat Value dipanggil.

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 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 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, mulailah dengan menentukan salah satu metode 'urutkan berdasarkan' untuk menentukan cara mengurutkan hasil.

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

Anda hanya dapat menggunakan satu 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 Menyusun Database Anda.

Panggilan ke metode OrderByChild() menentukan kunci turunan sebagai dasar pengurutan hasil. Dalam kasus ini, hasil diurutkan berdasarkan nilai "score" dalam setiap turunan. Untuk informasi lebih lanjut mengenai metode pengurutan jenis data lainnya, lihat Metode pengurutan data kueri.

Memfilter data

Untuk memfilter data, Anda dapat menggabungkan metode batas atau rentang mana pun 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 beberapa fungsi batas atau rentang. Misalnya, Anda dapat menggabungkan metode StartAt() dan EndAt() untuk membatasi hasil ke rentang nilai tertentu.

Sekalipun hanya ada 1 kueri yang cocok, snapshot tetaplah sebuah daftar yang hanya memuat 1 item.

Membatasi jumlah hasil

Anda dapat menggunakan metode LimitToFirst() dan LimitToLast() untuk menetapkan jumlah turunan maksimum 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 diaktifkan untuk setiap item.

Saat item berubah, Anda akan menerima callback ChildAdded untuk item yang masuk ke kueri dan callback ChildRemoved untuk item yang keluar dari kueri, 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
    }

Filter 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 class Query.

`OrderByChild`

Jika Anda menggunakan OrderByChild(), data yang berisi kunci turunan yang ditentukan akan diurutkan sebagai berikut:

Turunan yang memiliki nilai null untuk kunci turunan yang ditentukan akan muncul terlebih dahulu.
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.
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.
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.
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.
Objek akan muncul terakhir, dan diurutkan secara leksikografis berdasarkan kunci dalam urutan menaik.

`OrderByKey`

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

Turunan dengan kunci yang bisa diurai sebagai bilangan bulat 32-bit berada di urutan atas, dan diurutkan dalam urutan menaik.
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(), namun yang digunakan adalah nilai node, bukan nilai kunci turunan yang ditentukan.