Mengambil Data

Membaca Data dengan GET

Kita bisa membaca data dari database Firebase dengan mengeluarkan permintaan GET ke endpoint URL-nya. Mari kita lanjutkan dengan contoh blog dari bagian sebelumnya dan membaca semua data postingan blog kita:

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Permintaan yang berhasil akan ditunjukkan oleh kode status HTTP 200 OK, dan responsnya akan berisi data yang diambil.

Menambahkan Parameter URI

REST API menerima beberapa parameter kueri ketika membaca data dari database Firebase. Di bawah ini adalah parameter yang paling sering digunakan. Untuk daftar lengkapnya, lihat Referensi REST API.

auth

Parameter permintaan auth mengizinkan akses ke data yang dilindungi oleh Firebase Realtime Database Security Rules, dan didukung oleh semua jenis permintaan. Argumennya bisa berupa rahasia aplikasi Firebase Anda atau token autentikasi, seperti yang dijelaskan dalam artikel Pengguna dalam Project Firebase. Dalam contoh berikut, kita akan mengirimkan permintaan GET dengan parameter auth, dengan CREDENTIAL sebagai rahasia aplikasi Firebase kita atau token autentikasi:

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

Jika flag debug token ditetapkan, informasi debug dapat ditemukan di header X-Firebase-Auth-Debug pada respons.

cetak

Jika print=pretty ditentukan, data akan ditampilkan dalam format yang dapat dibaca manusia.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Jika print=silent ditentukan, 204 No Content akan ditampilkan saat berhasil.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

callback

Untuk membuat panggilan REST dari browser web di seluruh domain, Anda dapat menggunakan JSONP untuk mengemas respons dalam fungsi callback JavaScript. Tambahkan callback= agar REST API mengemas data yang ditampilkan dalam fungsi callback yang Anda tentukan. Contoh:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

shallow

Ini adalah fitur canggih yang dirancang untuk membantu Anda bekerja dengan set data besar tanpa perlu mendownload semuanya. Untuk menggunakannya, tambahkan shallow=true sebagai parameter. Ini akan membatasi kedalaman data yang ditampilkan. Jika data pada lokasi tersebut adalah JSON sederhana (string, angka, atau boolean), nilainya akan ditampilkan. Jika snapshot data di lokasi adalah objek JSON, nilai untuk setiap kunci akan terpotong menjadi true. Misalnya, dengan menggunakan data berikut:

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

Cobalah dengan permintaan curl ini:

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

shallow tidak dapat digunakan dengan parameter kueri "memfilter data" apa pun.

timeout

Gunakan ini untuk membatasi waktu baca yang dibutuhkan di sisi server. Permintaan baca yang tidak selesai dalam waktu yang ditentukan akan berakhir dengan error HTTP 400. Ini sangat berguna ketika Anda mengharapkan transfer data kecil dan tidak ingin menunggu terlalu lama untuk mengambil sub-hierarki yang mungkin berukuran besar. Waktu baca yang sebenarnya dapat bervariasi berdasarkan ukuran data dan cache.

Tentukan timeouts menggunakan format berikut: 3ms, 3s, atau 3min, dengan angka dan satuan. Jika tidak ditentukan, batas timeout maksimum sebesar 15min akan diterapkan. Jika timeout tidak positif, atau melebihi batas maksimum, permintaan akan ditolak dengan error HTTP 400. Dalam contoh berikut, permintaan GET menyertakan timeout sebesar 10 detik.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Memfilter Data

Kita dapat membuat kueri untuk memfilter data berdasarkan berbagai faktor. Untuk memulai, tetapkan cara Anda memfilter data menggunakan parameter orderBy. Kemudian, gabungkan orderBy dengan lima parameter lain mana pun: limitToFirst, limitToLast, startAt, endAt, dan equalTo.

Hasil filter data ditampilkan tidak berurutan: Ketika menggunakan REST API, hasil filter ditampilkan dalam urutan yang tidak ditentukan karena penafsir JSON tidak memberlakukan pengurutan apa pun. Jika Anda menganggap urutan data penting, urutkan hasil dalam aplikasi setelah data ditampilkan dari Firebase.

Karena kami semua di Firebase suka dinosaurus, kami akan menggunakan cuplikan dari contoh database fakta dinosaurus untuk menunjukkan bagaimana Anda bisa memfilter data:

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

Kita dapat memfilter data menggunakan salah satu dari tiga cara berikut: berdasarkan kunci turunan, kunci, atau nilai. Kueri dimulai dengan salah satu parameter ini, lalu harus dikombinasikan dengan satu atau beberapa parameter berikut: startAt, endAt, limitToFirst, limitToLast, atau equalTo.

Memfilter berdasarkan kunci turunan yang ditentukan

Kita dapat memfilter node berdasarkan kunci turunan yang sama dengan meneruskan kunci tersebut ke parameter orderBy. Misalnya, untuk mengambil semua dinosaurus dengan tinggi lebih dari 3, kita bisa melakukan hal berikut:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Setiap node yang tidak memiliki kunci turunan yang sesuai dengan filter akan diurutkan dengan nilai null. Untuk mempelajari detail mengenai cara data diurutkan, baca artikel Metode Pengurutan Data.

Firebase juga mendukung pengurutan kueri berdasarkan turunan bertingkat yang dalam, bukan hanya turunan satu tingkat di bawah. Hal ini berguna jika Anda memiliki data bertingkat yang dalam seperti ini:

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

Untuk kueri tentang tinggi, sekarang kita menggunakan lokasi lengkap ke objek dan bukan kunci tunggal:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

Kueri hanya bisa memfilter berdasarkan satu kunci pada satu waktu. Penggunaan parameter orderBy beberapa kali pada permintaan yang sama akan memunculkan error.

Menambahkan Pengindeksan ke Firebase Realtime Database Security Rules: Jika menggunakan orderBy di aplikasi, Anda harus menentukan kunci yang akan diindeks melalui aturan .indexOn di Firebase Realtime Database Security Rules. Baca dokumentasi tentang aturan .indexOn untuk mengetahui informasi lebih lanjut.

Memfilter berdasarkan kunci

Kita juga dapat memfilter node berdasarkan kuncinya menggunakan parameter orderBy="$key". Contoh berikut mengambil semua dinosaurus yang namanya diawali huruf a sampai m:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

Memfilter berdasarkan nilai

Kita bisa memfilter node berdasarkan nilai kunci turunannya menggunakan parameter orderBy="$value". Anggap saja para dinosaurus sedang mengadakan kompetisi olahraga dino, dan kita mengikuti perkembangan skor mereka dalam format berikut:

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

Untuk mengambil semua dinosaurus dengan skor di atas 50, kita bisa membuat permintaan berikut:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

Baca bagian Metode Pengurutan Data untuk mendapatkan penjelasan tentang pengurutan nilai null, boolean, string, dan objek jika orderBy="$value" digunakan.

Menambahkan Pengindeksan ke Firebase Realtime Database Security Rules: Jika menggunakan orderBy="$value" di aplikasi, Anda harus menambahkan .value ke aturan pada indeks yang sesuai. Baca dokumentasi tentang aturan .indexOn untuk mengetahui informasi lebih lanjut.

Pemfilteran Kompleks

Kita dapat menggabungkan beberapa parameter untuk membuat kueri yang lebih kompleks.

Kueri Batas

Parameter limitToFirst dan limitToLast digunakan untuk menetapkan jumlah turunan maksimum yang akan menerima data. Jika 100 ditetapkan sebagai batasnya, hanya 100 turunan yang cocok yang akan kita terima. Jika pesan yang tersimpan dalam database kurang dari 100, maka kita akan menerima setiap turunan. Namun, jika ada lebih dari 100 pesan, kita hanya akan menerima data untuk 100 pesan. Jika limitToFirst digunakan, pesan yang diterima adalah 100 pesan pertama yang diurutkan. Jika limitToLast digunakan, pesan yang diterima adalah 100 pesan terakhir yang diurutkan.

Dengan menggunakan database fakta dinosaurus dan orderBy, kita bisa menemukan dua dinosaurus terberat:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

Demikian pula, kita bisa menemukan dua dinosaurus terpendek dengan menggunakan limitToFirst:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

Kita juga bisa melakukan kueri batas dengan orderBy="$value". Jika ingin membuat papan peringkat yang menampilkan tiga kompetitor dengan skor tertinggi dalam turnamen olahraga dino, kita bisa melakukan hal berikut:

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

Kueri Rentang

Dengan menggunakan startAt, endAt, dan equalTo, kita dapat memilih titik awal dan akhir arbitrer untuk kueri yang kita buat. Misalnya, jika ingin menemukan semua dinosaurus yang memiliki tinggi minimal tiga meter, kita bisa menggabungkan orderBy dan startAt:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Kita bisa menggunakan endAt untuk menemukan semua dinosaurus yang namanya muncul sebelum Pterodactyl secara leksikografis:

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

startAt dan endAt bersifat inklusif, yang berarti "pterodactyl" akan cocok dengan kueri di atas.

Kita bisa menggabungkan startAt dan endAt untuk membatasi kedua ujung kueri. Contoh berikut menemukan semua dinosaurus yang namanya dimulai dengan huruf "b":

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

Karakter \uf8ff yang digunakan dalam kueri di atas adalah poin kode yang sangat tinggi dalam rentang Unicode. Karena karakter itu merupakan yang paling sering digunakan dalam Unicode, kueri akan mencocokkan semua nilai yang dimulai dengan huruf b.

Kueri rentang juga berguna ketika Anda perlu memisahkan data Anda menjadi beberapa halaman.

Menggabungkan semuanya

Kita bisa menggabungkan semua teknik ini untuk membuat kueri yang kompleks. Misalnya, mungkin Anda ingin menemukan nama semua dinosaurus yang tingginya lebih pendek dari atau sama dengan jenis favorit kami, Stegosaurus:

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

Metode Pengurutan Data

Bagian ini menjelaskan cara data diurutkan ketika menggunakan tiga parameter filter yang berbeda.

REST API Menampilkan Hasil Tanpa Diurutkan: Penafsir JSON tidak memberlakukan pengurutan apa pun pada rangkaian hasil. Meskipun orderBy dapat digunakan bersama dengan startAt, endAt, limitToFirst, atau limitToLast untuk menampilkan subkumpulan data, hasil yang ditampilkan tidak akan diurutkan. Oleh sebab itu, pengurutan hasil secara manual mungkin diperlukan jika urutan tersebut penting.

orderBy

Ketika menggunakan orderBy dengan nama suatu kunci turunan, 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 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.

Hasil filter akan ditampilkan secara tidak berurutan. Jika Anda menganggap urutan data penting, urutkan hasil dalam aplikasi setelah data ditampilkan dari Firebase.

orderBy="$key"

Ketika menggunakan parameter orderBy="$key" untuk mengurutkan data Anda, data tersebut akan ditampilkan dalam urutan menaik berdasarkan kunci seperti berikut. Perlu diingat bahwa kunci hanya bisa berupa string.

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

orderBy="$value"

Ketika menggunakan parameter orderBy="$value" untuk mengurutkan data, turunan akan diurutkan berdasarkan nilainya. Kriteria pengurutannya sama seperti data yang diurutkan berdasarkan kunci turunan, namun yang digunakan adalah nilai node, bukan nilai kunci turunan yang ditentukan.

orderBy="$priority"

Ketika menggunakan parameter orderBy="$priority" untuk mengurutkan data, pengurutan turunan ditentukan berdasarkan prioritas dan kuncinya seperti berikut. Perlu diingat bahwa nilai prioritas hanya bisa berupa angka atau string.

Prioritas angka disimpan dan diurutkan sebagai angka floating-point presisi ganda IEEE 754. Kunci selalu disimpan sebagai string dan diperlakukan sebagai angka hanya ketika bisa diurai sebagai bilangan bulat 32-bit.

1. Turunan tanpa prioritas (default) akan muncul pertama.
2. Turunan dengan angka sebagai prioritasnya akan muncul berikutnya. Turunan ini diurutkan secara numerik berdasarkan prioritas, dari kecil ke besar.
3. Turunan dengan string sebagai prioritasnya akan muncul terakhir. Turunan ini diurutkan secara leksikografis berdasarkan prioritas.
4. Setiap kali ada dua turunan yang memiliki prioritas sama (termasuk tanpa prioritas), keduanya akan diurutkan berdasarkan kunci. Kunci numerik muncul lebih dahulu (diurutkan secara numerik), dan diikuti kunci yang tersisa (diurutkan secara leksikografis).

Untuk informasi lebih lanjut tentang prioritas, lihat referensi API.

Streaming dari REST API

Endpoint Firebase REST mendukung protokol EventSource/Server-Sent Events, sehingga memudahkan kita mengalirkan perubahan ke satu lokasi dalam database Firebase.

Untuk memulai streaming, lakukan hal berikut:

1. Tetapkan header Accept klien ke text/event-stream
2. Patuhi Pengalihan HTTP, terutama kode status HTTP 307
3. Sertakan parameter kueri auth jika lokasi database Firebase memerlukan izin baca

Sebagai balasannya, server akan mengirimkan peristiwa bernama sebagai status data pada perubahan URL yang diminta. Struktur pesan ini sesuai dengan protokol EventSource:

event: event name
data: JSON encoded data payload

Server mungkin akan mengirimkan peristiwa berikut:

put	Data yang dienkode JSON akan menjadi objek dengan dua kunci: jalur dan data Jalur akan menunjuk ke lokasi yang relatif terhadap URL permintaan Klien harus mengganti semua data di lokasi tersebut dalam cache-nya dengan data yang diberikan dalam pesan
patch	Data yang dienkode JSON akan menjadi objek dengan dua kunci: jalur dan data Jalur akan menunjuk ke lokasi yang relatif terhadap URL permintaan Untuk setiap kunci dalam data, klien harus mengganti kunci yang sesuai dalam cache-nya dengan data untuk kunci tersebut dalam pesan
keep-alive	Data untuk peristiwa ini adalah null, tindakan tidak diperlukan
batal	Data untuk peristiwa ini adalah null Peristiwa ini akan dikirim jika Firebase Realtime Database Security Rules menyebabkan pembacaan di lokasi yang diminta tidak lagi diizinkan
auth_revoked	Data untuk peristiwa ini adalah string yang menunjukkan bahwa kredensial sudah tidak berlaku Peristiwa ini akan dikirim jika parameter auth yang disediakan tidak lagi valid

Berikut contoh rangkaian peristiwa yang mungkin akan dikirim oleh server:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}


// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}


// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

Jika Anda menggunakan Go, cobalah Firego, yaitu wrapper pihak ketiga untuk Firebase REST dan Streaming API.