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 agar dapat menggunakan Firebase.

  • Jika project Unity Anda telah menggunakan Firebase, berarti project tersebut telah terdaftar dan dikonfigurasi 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 detail seputar tugas penyiapan awal ini di artikel Menambahkan Firebase ke project Unity.

Perlu diperhatikan bahwa penambahan Firebase ke project Unity Anda memerlukan tindakan baik di Firebase console maupun 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 satu kali ke GetValueAsync() atau disertakan ke peristiwa pada referensi FirebaseDatabase. Pemroses peristiwa akan dipanggil satu kali untuk status awal data, dan dipanggil lagi setiap kali data berubah.

Catatan: Secara default, akses baca dan tulis pada database Anda dibatasi sehingga hanya pengguna terautentikasi yang dapat membaca atau menulis data. Untuk memulai tanpa menyiapkan Authentication, Anda dapat mengonfigurasi aturan untuk akses publik. Tindakan ini membuat database terbuka bagi siapa saja, termasuk orang yang tidak menggunakan aplikasi Anda. Oleh sebab itu, pastikan kembali untuk membatasi database Anda saat menyiapkan autentikasi.

Mendapatkan DatabaseReference

Untuk membaca data dari database, Anda perlu instance 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;
  }
}

Membaca data satu kali

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().ContinueWithOnMainThread(task => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Mendeteksi peristiwa

Anda dapat menambahkan pemroses peristiwa untuk memantau perubahan data:

Peristiwa	Penggunaan standar
ValueChanged	Membaca dan memproses perubahan pada seluruh konten jalur.
ChildAdded	Mengambil daftar item atau memproses penambahan ke 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	Memproses perubahan urutan item dalam daftar yang diurutkan. Peristiwa ChildMoved selalu mengikuti peristiwa ChildChanged yang menyebabkan urutan item berubah (berdasarkan metode 'urutkan menurut' saat ini).

Peristiwa ValueChanged

Anda dapat menggunakan peristiwa ValueChanged untuk memantau perubahan konten di jalur tertentu. Peristiwa ini dipicu sekali ketika pemroses dipasang dan dipicu lagi setiap kali terjadi perubahan pada data, termasuk pada turunannya. Callback peristiwa diberikan snapshot yang berisi semua data di lokasi tersebut, termasuk data turunan. Jika tidak ada data, snapshot yang ditampilkan adalah null.

Penting: Peristiwa ValueChanged dipicu setiap kali data diubah pada referensi database yang ditentukan, termasuk perubahan pada turunannya. Untuk membatasi ukuran snapshot, tambahkan pemroses hanya pada level tertinggi yang diperlukan untuk memantau perubahan. Misalnya, tidak dianjurkan untuk memasang pemroses peristiwa pada root database Anda.

Contoh berikut menunjukkan game yang mengambil skor 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 memantau peristiwa menggunakan DatabaseReference yang memiliki jalur 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 operasi seperti turunan baru yang ditambahkan melalui metode Push() atau turunan yang diperbarui melalui metode UpdateChildrenAsync(). Secara bersama-sama, setiap metode ini dapat berguna untuk memproses perubahan pada 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 satu kali untuk setiap turunan yang ada, dan dipicu lagi setiap kali ada turunan baru yang ditambahkan ke lokasi yang ditetapkan. Pemroses diberikan snapshot yang berisi data turunan baru.

Peristiwa ChildChanged dipicu 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 pemroses peristiwa berisi data turunan yang diperbarui.

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 dipicu oleh update yang menyebabkan pengurutan ulang turunan. Peristiwa ini digunakan dengan data yang diurutkan dengan OrderByChild atau OrderByValue.

Mengurutkan dan memfilter data

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

Catatan: Biaya pemfilteran dan pengurutan bisa menjadi mahal, terutama jika dilakukan pada klien. Jika aplikasi Anda menggunakan kueri, tentukan aturan .indexOn untuk mengindeks kunci tersebut pada server dan meningkatkan performa kueri, seperti yang dijelaskan dalam artikel Mengindeks Data.

Mengurutkan data

Untuk mengambil data yang diurutkan, mulai dengan menentukan salah satu metode 'urutkan menurut' guna menentukan cara pengurutan hasil:

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

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

Contoh berikut menunjukkan bagaimana Anda bisa memantau 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 pemroses peristiwa valuechanged akan menyinkronkan klien dengan papan peringkat dalam database, yang diurutkan berdasarkan skor setiap entri. Anda dapat membaca selengkapnya tentang penyusunan struktur data secara efisien di bagian Membuat Struktur Database.

Panggilan ke metode OrderByChild() menentukan kunci turunan yang dipakai sebagai dasar pengurutan hasil. Dalam kasus ini, hasil diurutkan menurut 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 salah satu metode batas atau rentang dengan metode 'urutkan menurut' 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 menurut' yang dipilih.
EndAt()	Menampilkan item yang lebih kecil atau sama dengan kunci atau nilai yang ditentukan, tergantung metode 'urutkan menurut' yang dipilih.
EqualTo()	Menampilkan item yang sama dengan kunci atau nilai yang ditentukan, tergantung metode 'urutkan menurut' yang dipilih.

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

Meskipun kueri hanya mendapatkan satu item yang cocok, snapshot-nya tetap berupa sebuah daftar, meski hanya memuat satu 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 ekuivalensi yang arbitrer untuk kueri. Hal ini dapat bermanfaat untuk penomoran halaman data atau menemukan item dengan turunan yang memiliki nilai tertentu.

Cara data kueri diurutkan

Bagian ini menjelaskan cara pengurutan data menggunakan setiap metode 'urutkan menurut' di class Query.

OrderByChild

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

1. Turunan yang memiliki nilai null untuk kunci turunan yang ditentukan akan muncul terlebih dahulu.
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 menurut 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 menurut kunci.
4. Turunan dengan nilai numerik akan muncul berikutnya, dan diurutkan menaik. Jika beberapa turunan memiliki nilai numerik yang sama untuk node turunan yang ditentukan, turunan tersebut akan diurutkan menurut kunci.
5. String muncul setelah angka, dan diurutkan secara leksikografis menaik. Jika beberapa turunan memiliki nilai yang sama untuk node turunan yang ditentukan, turunan tersebut akan diurutkan secara leksikografis menurut kunci.
6. Objek akan muncul terakhir, dan diurutkan secara leksikografis menaik menurut kunci.

OrderByKey

Data yang diurutkan menggunakan OrderByKey() akan ditampilkan dalam urutan menaik menurut kunci.

1. Turunan dengan kunci yang bisa diurai sebagai bilangan bulat 32-bit akan muncul terlebih dahulu, dan diurutkan menaik.
2. Turunan dengan nilai string sebagai kuncinya akan muncul berikutnya, dan diurutkan secara leksikografis menaik.

OrderByValue

Jika menggunakan OrderByValue(), turunan akan diurutkan menurut nilainya. Kriteria urutan sama seperti di OrderByChild(), namun yang digunakan adalah nilai node, bukan nilai kunci turunan yang ditentukan.