Dokumen ini membahas dasar-dasar pengambilan data serta cara mengurutkan dan memfilter data Firebase.
Sebelum kamu memulai
Sebelum dapat menggunakan Realtime Database , Anda perlu:
Daftarkan proyek Unity Anda dan konfigurasikan untuk menggunakan Firebase.
Jika project Unity Anda sudah menggunakan Firebase, maka project tersebut sudah terdaftar dan dikonfigurasi untuk Firebase.
Jika Anda tidak memiliki proyek Unity, Anda dapat mengunduh contoh aplikasi .
Tambahkan Firebase Unity SDK (khususnya,
FirebaseDatabase.unitypackage
) ke proyek Unity Anda.
Perhatikan bahwa menambahkan Firebase ke proyek Unity Anda melibatkan tugas di konsol Firebase dan di proyek Unity terbuka Anda (misalnya, Anda mengunduh file konfigurasi Firebase dari konsol, lalu memindahkannya ke proyek Unity Anda).
Mengambil Data
Data Firebase diambil dengan panggilan satu kali ke GetValueAsync() atau melampirkan ke peristiwa di referensi FirebaseDatabase
. Pendengar acara dipanggil sekali untuk keadaan awal data dan dipanggil lagi setiap kali data berubah.
Dapatkan Referensi Basis Data
Untuk membaca data dari database, Anda memerlukan instance dari 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 sekali
Anda dapat menggunakan metode GetValueAsync
untuk membaca snapshot statis konten di jalur yang diberikan satu kali. Hasil tugas akan berisi snapshot yang berisi semua data di lokasi tersebut, termasuk data anak. Jika tidak ada data, snapshot yang dikembalikan 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... } });
Dengarkan acara
Anda dapat menambahkan pendengar acara untuk berlangganan perubahan pada data:
Peristiwa | Penggunaan tipikal |
---|---|
ValueChanged | Baca dan dengarkan perubahan pada seluruh konten jalur. |
ChildAdded | Ambil daftar item atau dengarkan penambahan ke daftar item. Penggunaan yang disarankan dengan ChildChanged dan ChildRemoved untuk memantau perubahan pada daftar. |
ChildChanged | Dengarkan perubahan pada item dalam daftar. Gunakan dengan ChildAdded dan ChildRemoved untuk memantau perubahan pada daftar. |
ChildRemoved | Dengarkan item yang dihapus dari daftar. Gunakan dengan ChildAdded dan ChildChanged untuk memantau perubahan pada daftar. |
ChildMoved | Dengarkan perubahan pada urutan item dalam daftar yang diurutkan. Event ChildMoved selalu mengikuti event ChildChanged yang menyebabkan urutan item berubah (berdasarkan metode order-by Anda saat ini). |
Acara ValueChanged
Anda dapat menggunakan acara ValueChanged
untuk berlangganan perubahan konten di jalur tertentu. Peristiwa ini dipicu sekali saat pemroses terpasang dan dipicu lagi setiap kali data, termasuk turunan, berubah. Panggilan balik peristiwa diteruskan snapshot yang berisi semua data di lokasi itu, termasuk data anak. Jika tidak ada data, snapshot yang dikembalikan 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 berisi data di lokasi yang ditentukan dalam database pada saat kejadian. Memanggil Value
pada snapshot mengembalikan Dictionary<string, object>
yang mewakili data. Jika tidak ada data di lokasi, pemanggilan Value
mengembalikan null
.
Dalam contoh ini, args.DatabaseError
juga diperiksa untuk melihat apakah pembacaan dibatalkan. Misalnya, pembacaan dapat dibatalkan jika klien tidak memiliki izin untuk membaca dari lokasi database Firebase. DatabaseError
akan menunjukkan mengapa kegagalan terjadi.
Anda nanti dapat berhenti berlangganan dari acara tersebut menggunakan DatabaseReference
apa pun yang memiliki jalur yang sama. Instance DatabaseReference
bersifat sementara dan dapat dianggap sebagai cara untuk mengakses jalur dan kueri apa pun.
FirebaseDatabase.DefaultInstance .GetReference("Leaders") .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged. }
Acara anak
Peristiwa anak dipicu sebagai respons terhadap operasi tertentu yang terjadi pada anak node dari operasi seperti anak baru yang ditambahkan melalui metode Push()
atau anak yang diperbarui melalui metode UpdateChildrenAsync()
. Masing-masing bersama-sama dapat berguna untuk mendengarkan perubahan pada node tertentu dalam database. Misalnya, game mungkin menggunakan metode ini bersama-sama untuk memantau aktivitas di 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 }
Acara ChildAdded
biasanya digunakan untuk mengambil daftar item dalam database Firebase. Acara ChildAdded
dimunculkan sekali untuk setiap anak yang ada dan sekali lagi setiap kali anak baru ditambahkan ke jalur yang ditentukan. Pendengar diberikan snapshot yang berisi data anak baru.
Acara ChildChanged
dimunculkan setiap kali simpul anak dimodifikasi. Ini termasuk modifikasi apa pun pada keturunan simpul anak. Ini biasanya digunakan bersamaan dengan ChildAdded
dan ChildRemoved
untuk merespons perubahan pada daftar item. Cuplikan yang diteruskan ke pendengar acara berisi data yang diperbarui untuk anak tersebut.
Acara ChildRemoved
dipicu saat anak langsung dihapus. Ini biasanya digunakan bersamaan dengan callback ChildAdded
dan ChildChanged
. Snapshot yang diteruskan ke callback event berisi data untuk anak yang dihapus.
Acara ChildMoved
dipicu setiap kali acara ChildChanged
dimunculkan oleh pembaruan yang menyebabkan penataan ulang anak. Ini digunakan dengan data yang dipesan dengan OrderByChild
atau OrderByValue
.
Menyortir dan memfilter data
Anda dapat menggunakan kelas Realtime Database Query
untuk mengambil data yang diurutkan berdasarkan kunci, nilai, atau nilai turunan. Anda juga dapat memfilter hasil yang diurutkan ke sejumlah hasil tertentu atau rentang kunci atau nilai.
Sortir data
Untuk mengambil data yang diurutkan, mulailah dengan menentukan salah satu metode urutkan demi untuk menentukan bagaimana hasil diurutkan:
metode | Penggunaan |
---|---|
OrderByChild() | Urutkan hasil berdasarkan nilai kunci anak yang ditentukan. | OrderByKey() | Urutan hasil dengan kunci anak. |
OrderByValue() | Urutkan hasil berdasarkan nilai anak. |
Anda hanya dapat menggunakan satu metode order-by pada satu waktu. Memanggil metode order-by beberapa kali dalam kueri yang sama akan menimbulkan kesalahan.
Contoh berikut menunjukkan bagaimana Anda dapat 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 mendefinisikan kueri yang bila digabungkan dengan pendengar peristiwa yang diubah nilai akan menyinkronkan klien dengan papan peringkat dalam database, diurutkan berdasarkan skor setiap entri. Anda dapat membaca lebih lanjut tentang menyusun data Anda secara efisien di Structure Your Database .
Panggilan ke metode OrderByChild()
menentukan kunci anak untuk mengurutkan hasil. Dalam hal ini, hasil diurutkan berdasarkan nilai "score"
nilai pada setiap anak. Untuk informasi selengkapnya tentang cara pengurutan tipe data lainnya, lihat Cara pengurutan data kueri .
Menyaring data
Untuk memfilter data, Anda bisa mengombinasikan salah satu metode batas atau rentang dengan metode urutkan saat membuat kueri.
metode | Penggunaan |
---|---|
LimitToFirst() | Menetapkan jumlah item maksimum yang akan dikembalikan dari awal daftar hasil yang diurutkan. |
LimitToLast() | Menetapkan jumlah item maksimum yang akan dikembalikan dari akhir daftar hasil yang diurutkan. |
StartAt() | Mengembalikan item yang lebih besar atau sama dengan kunci atau nilai yang ditentukan bergantung pada metode urutkan menurut yang dipilih. |
EndAt() | Mengembalikan item yang kurang dari atau sama dengan kunci atau nilai yang ditentukan bergantung pada metode urutkan menurut yang dipilih. |
EqualTo() | Mengembalikan item yang sama dengan kunci atau nilai yang ditentukan bergantung pada metode urutkan berdasarkan yang dipilih. |
Berbeda dengan metode order-by, Anda dapat menggabungkan beberapa fungsi limit atau range. Misalnya, Anda dapat menggabungkan metode StartAt()
dan EndAt()
untuk membatasi hasil pada rentang nilai tertentu.
Meskipun hanya ada satu kecocokan untuk kueri, snapshot tetap berupa daftar; itu hanya berisi satu item.
Batasi 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, awalnya Anda hanya menerima hingga 100 callback ChildAdded
. Jika Anda memiliki kurang dari 100 item yang disimpan di database Firebase, callback ChildAdded
akan diaktifkan untuk setiap item.
Saat item berubah, Anda menerima callback ChildAdded
untuk item yang memasukkan kueri dan callback ChildRemoved
untuk item yang keluar sehingga jumlah totalnya tetap 100.
Misalnya, kode di bawah 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 arbitrer untuk kueri. Ini dapat berguna untuk membuat nomor halaman data atau menemukan item dengan turunan yang memiliki nilai tertentu.
Bagaimana data kueri diurutkan
Bagian ini menjelaskan cara data diurutkan menurut masing-masing metode urutkan menurut di kelas Query
.
OrderByChild
Saat menggunakan OrderByChild()
, data yang berisi kunci anak tertentu diurutkan sebagai berikut:
- Anak-anak dengan nilai
null
untuk kunci anak yang ditentukan didahulukan. - Anak-anak dengan nilai
false
untuk kunci anak yang ditentukan muncul berikutnya. Jika beberapa anak memiliki nilaifalse
, mereka diurutkan secara leksikografis berdasarkan kunci. - Anak-anak dengan nilai
true
untuk kunci anak yang ditentukan muncul berikutnya. Jika beberapa anak memiliki nilaitrue
, mereka diurutkan secara leksikografis berdasarkan kunci. - Anak-anak dengan nilai numerik datang berikutnya, diurutkan dalam urutan menaik. Jika beberapa anak memiliki nilai numerik yang sama untuk simpul anak yang ditentukan, mereka akan diurutkan berdasarkan kunci.
- String muncul setelah angka dan diurutkan secara leksikografis dalam urutan menaik. Jika beberapa turunan memiliki nilai yang sama untuk simpul turunan tertentu, mereka diurutkan secara leksikografis berdasarkan kunci.
- Objek datang terakhir dan diurutkan secara leksikografis dengan kunci dalam urutan menaik.
OrderByKey
Saat menggunakan OrderByKey()
untuk mengurutkan data Anda, data dikembalikan dalam urutan menaik berdasarkan kunci.
- Anak-anak dengan kunci yang dapat diurai sebagai bilangan bulat 32-bit didahulukan, diurutkan dalam urutan menaik.
- Anak-anak dengan nilai string sebagai kuncinya muncul berikutnya, diurutkan secara leksikografis dalam urutan menaik.
OrderByValue
Saat menggunakan OrderByValue()
, turunan diurutkan berdasarkan nilainya. Kriteria pengurutannya sama seperti di OrderByChild()
, kecuali nilai node digunakan sebagai ganti nilai kunci anak yang ditentukan.