Buka konsol

Mengambil Data dengan Firebase Realtime Database untuk C++

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

Sebelum memulai

Pastikan Anda telah menyiapkan aplikasi dan dapat mengakses database, seperti yang dijelaskan dalam panduan Get Started.

Mengambil Data

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

Mendapatkan DatabaseReference

Untuk menulis data ke Database, Anda perlu instance DatabaseReference:

    // Get the root reference location of the database.
    firebase::database::DatabaseReference dbref = database->GetReference();

Membaca data sekali

Anda dapat menggunakan metode GetValue() untuk membaca snapshot statis konten di jalur 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.

  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

Pada saat itu, permintaan telah dibuat, tetapi harus menunggu Future selesai untuk dapat membaca nilai. Karena game biasanya dijalankan dalam loop, dan tidak terlalu dikendalikan oleh callback dibanding aplikasi lain, Anda biasanya akan menanyakan penyelesaian.

  // In the game loop that polls for the result...

  if (result.status() != firebase::kFutureStatusPending) {
    if (result.status() != firebase::kFutureStatusComplete) {
      LogMessage("ERROR: GetValue() returned an invalid result.");
      // Handle the error...
    } else if (result.error() != firebase::database::kErrorNone) {
      LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
                 result.error_message());
      // Handle the error...
    } else {
      firebase::database::DataSnapshot snapshot = result.result();
      // Do something with the snapshot...
    }
  }

Hal ini menunjukkan beberapa pemeriksaan error dasar, lihat referensi firebase::Future untuk mengetahui informasi lebih lanjut tentang pemeriksaan error, serta cara menentukan kapan hasilnya siap.

Mendeteksi peristiwa

Anda dapat menambahkan listener untuk berlangganan perubahan data:

Kelas dasar ValueListener

Callback Penggunaan standar
OnValueChanged Membaca dan mendeteksi perubahan pada seluruh konten di sebuah lokasi.

Kelas dasar OnChildListener

OnChildAdded Mengambil daftar item atau mendeteksi penambahan daftar item. Disarankan untuk digunakan dengan OnChildChanged dan OnChildRemoved untuk memantau perubahan daftar.
OnChildChanged Mendeteksi perubahan pada item dalam daftar. Gunakan dengan OnChildAdded dan OnChildRemoved untuk memantau perubahan daftar.
OnChildRemoved Mendeteksi item yang dihapus dari daftar. Gunakan dengan OnChildAdded dan OnChildChanged untuk memantau perubahan daftar.
OnChildMoved Mendeteksi perubahan urutan item dalam urutan daftar. Callback OnChildMoved selalu mengikuti callback OnChildChanged karena adanya perubahan urutan item (berdasarkan metode 'urutkan berdasarkan' saat ini).

Kelas ValueListener

Anda dapat menggunakan callback OnValueChanged untuk berlangganan perubahan konten di lokasi tertentu. Callback ini terpicu 1 kali ketika listener terpasang dan terpicu lagi setiap kali terjadi perubahan data, termasuk turunannya. Callback mendapatkan 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:

  class LeadersValueListener : public firebase::database::ValueListener {
   public:
    void OnValueChanged(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
                 error_message);
    }
  };

  // Elsewhere in the code...

  LeadersValueListener* listener = new LeadersValueListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

Hasil Future&ltDataSnaphot&gt berisi data di lokasi yang ditentukan dalam database pada saat peristiwa berlangsung. Memanggil value() pada snapshot akan menampilkan Variant yang mewakili data tersebut.

Dalam contoh ini, metode OnCancelled juga diganti untuk mengetahui apakah pembacaan dibatalkan. Misalnya, proses baca bisa dibatalkan jika klien tidak memiliki izin untuk membaca dari lokasi database Firebase. database::Error akan menunjukkan mengapa kegagalan terjadi.

Kelas ChildListener

Peristiwa turunan dipicu sebagai respons terhadap operasi tertentu yang terjadi pada turunan node dari suatu operasi, seperti turunan baru yang ditambahkan melalui metode PushChild() atau turunan yang sedang diupdate melalui metode UpdateChildren(). 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:

  class SessionCommentsChildListener : public firebase::database::ChildListener {
   public:
    void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
                        const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnChildRemoved(
        const firebase::database::DataSnapshot& snapshot) override {
      // Do something with the data in snapshot ...
    }
    void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
                      const char* previous_sibling) override {
      // Do something with the data in snapshot ...
    }
    void OnCancelled(const firebase::database::Error& error_code,
                     const char* error_message) override {
      LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
                 error_code, error_message);
    }
  };

  // elsewhere ....

  SessionCommentsChildListener* listener = new SessionCommentsChildListener();
  firebase::Future&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

Callback OnChildAdded biasanya digunakan untuk mengambil daftar item di database Firebase. Callback OnChildAdded dipanggil 1 kali untuk setiap turunan yang ada, dan dipanggil lagi setiap kali ada turunan baru yang ditambahkan ke lokasi yang ditetapkan. Listener mendapatkan cuplikan yang berisi data turunan baru.

Callback OnChildChanged dipanggil setiap kali node turunan diubah. Ini juga termasuk perubahan keturunan dari node turunan. Peristiwa ini biasanya digunakan bersama dengan panggilan OnChildAdded dan OnChildRemoved untuk menanggapi perubahan daftar item. Snapshot yang diteruskan ke listener berisi data turunan yang telah diupdate.

Callback OnChildRemoved dipicu ketika data turunan langsung dihapus. Peristiwa ini biasanya digunakan bersama dengan callback OnChildAdded dan OnChildChanged. Snapshot yang diteruskan ke callback berisi data turunan yang dihapus.

Callback OnChildMoved dipicu setiap kali panggilan OnChildChanged 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 1 kueri akan menghasilkan error.

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

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score");

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

Fungsi ini akan menentukan firebase::Query yang akan menyinkronkan klien dengan papan peringkat dalam database jika dikombinasikan dengan ValueListener, dan diurutkan berdasarkan skor setiap entri. Anda dapat membaca selengkapnya tentang penyusunan struktur data secara efisien di bagian Menyusun 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 yang diberikan. Misalnya, jika Anda menggunakan LimitToFirst() untuk menetapkan batas 100, pada awalnya Anda hanya akan menerima hingga 100 callback OnChildAdded. Jika Anda memiliki kurang dari 100 item yang disimpan dalam database Firebase, callback OnChildAdded akan dikeluarkan untuk setiap item.

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

Misalnya, kode berikut menampilkan skor teratas dari papan peringkat:

  firebase::database::Query query =
    dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);

  // To get the resulting DataSnapshot either use query.GetValue() and poll the
  // future, or use query.AddValueListener() and register to handle the
  // OnValueChanged callback.

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.

Langkah Berikutnya