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 dikonfigurasi 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 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.
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
.
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 bisa menggunakan class Query
Realtime Database 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.
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:
- 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 nilaifalse
, turunan tersebut akan diurutkan secara leksikografis menurut kunci. - Turunan yang memiliki nilai
true
untuk kunci turunan yang ditentukan akan muncul berikutnya. Jika beberapa turunan memiliki nilaitrue
, turunan tersebut akan diurutkan secara leksikografis menurut kunci. - 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.
- 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.
- Objek akan muncul terakhir, dan diurutkan secara leksikografis menaik menurut kunci.
OrderByKey
Data yang diurutkan menggunakan OrderByKey()
akan ditampilkan dalam urutan menaik menurut kunci.
- Turunan dengan kunci yang bisa diurai sebagai bilangan bulat 32-bit akan muncul terlebih dahulu, dan diurutkan menaik.
- 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.