API REST Basis Data Firebase

Penggunaan API

Anda dapat menggunakan URL Firebase Realtime Database apa pun sebagai titik akhir REST. Yang perlu Anda lakukan hanyalah menambahkan .json di akhir URL dan mengirim permintaan dari klien HTTPS favorit Anda.

HTTPS diperlukan. Firebase hanya merespons lalu lintas terenkripsi sehingga data Anda tetap aman.

DAPATKAN - Membaca Data

Data dari Realtime Database Anda dapat dibaca dengan mengeluarkan permintaan HTTP GET ke titik akhir. Contoh berikut menunjukkan bagaimana Anda dapat mengambil nama pengguna yang sebelumnya Anda simpan di Realtime Database.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Permintaan yang berhasil ditunjukkan dengan kode status HTTP 200 OK . Responsnya berisi data yang terkait dengan jalur dalam permintaan GET .

{ "first": "Jack", "last": "Sparrow" }

PUT - Menulis Data

Anda dapat menulis data dengan permintaan PUT .

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Permintaan yang berhasil ditunjukkan dengan kode status HTTP 200 OK . Responsnya berisi data yang ditentukan dalam permintaan PUT .

{ "first": "Jack", "last": "Sparrow" }

POST - Mendorong Data

Untuk mencapai hal yang setara dengan metode JavaScript push() (lihat Daftar Data ), Anda dapat mengeluarkan permintaan POST .

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

Permintaan yang berhasil ditunjukkan dengan kode status HTTP 200 OK . Responsnya berisi nama anak dari data baru yang ditentukan dalam permintaan POST .

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - Memperbarui Data

Anda dapat memperbarui turunan tertentu di suatu lokasi tanpa menimpa data yang ada menggunakan permintaan PATCH . Anak yang diberi nama dalam data yang ditulis dengan PATCH akan ditimpa, tetapi anak yang dihilangkan tidak akan dihapus. Ini setara dengan fungsi JavaScript update() .

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

Permintaan yang berhasil ditunjukkan dengan kode status HTTP 200 OK . Responsnya berisi data yang ditentukan dalam permintaan PATCH .

{ "last": "Jones" }

HAPUS - Menghapus Data

Anda dapat menghapus data dengan permintaan DELETE :

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Permintaan DELETE yang berhasil ditunjukkan dengan kode status HTTP 200 OK dengan respons yang berisi JSON null .

Penggantian Metode

Jika Anda melakukan panggilan REST dari browser yang tidak mendukung metode sebelumnya, Anda dapat mengganti metode permintaan dengan membuat permintaan POST dan mengatur metode Anda menggunakan header permintaan X-HTTP-Method-Override .

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Anda juga dapat menggunakan parameter kueri x-http-method-override .

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Permintaan Bersyarat

Permintaan bersyarat, yang setara dengan operasi transaksi SDK REST, memperbarui data sesuai dengan kondisi tertentu. Lihat gambaran umum alur kerja dan pelajari lebih lanjut tentang permintaan bersyarat untuk REST di Menyimpan Data .

Firebase ETag

Firebase ETag adalah pengidentifikasi unik untuk data saat ini di lokasi tertentu. Jika data berubah di lokasi tersebut, ETag juga berubah. Firebase ETag harus ditentukan di header untuk permintaan REST awal (biasanya GET , tetapi bisa berupa apa pun selain PATCH ).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

jika-cocok

Kondisi if-match menentukan nilai ETag untuk data yang ingin Anda perbarui. Jika Anda menggunakan ketentuan tersebut, Realtime Database hanya menyelesaikan permintaan jika ETag yang ditentukan dalam permintaan tulis cocok dengan ETag data yang ada di database. Ambil ETag di lokasi dengan permintaan Firebase ETag. Jika Anda ingin menimpa lokasi mana pun yang null, gunakan null_etag .

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Tanggapan yang diharapkan

Tabel berikut memberikan gambaran umum tentang respons yang diharapkan untuk setiap jenis permintaan, berdasarkan kecocokan ETag.

Jenis Permintaan 'X-Firebase-ETag: benar' Pertandingan ETag
if_match: <matching etag>		 ETag tidak cocok
if_match: <no matching etag>
MENDAPATKAN Status/Isi Tanggapan 200: "<data_at_path>" 400: "...tidak didukung.." 400: "...tidak didukung.."
Menambahkan Header ETag: <ETag_of_data> T/A T/A
MELETAKKAN Status/Isi Tanggapan 200: "<put_data>" 200: "<put_data>" 412: "...ETag tidak cocok.."
Menambahkan Header ETag: <ETag_of_put_data> T/A ETag: <database_ETag>
POS Status/Isi Tanggapan 200: "<post_data>" 400: "...tidak didukung.." 400: "...tidak didukung.."
Menambahkan Header ETag: <ETag_of_post_data> T/A T/A
tambalan Status/Isi Tanggapan 400: "...tidak didukung.." 400: "...tidak didukung.." 400: "...tidak didukung.."
Menambahkan Header T/A T/A T/A
MENGHAPUS Status/Isi Tanggapan 200: batal 200: "<data_after_put>" 412: "...ETag tidak cocok.."
Menambahkan Header ETag: <ETag_of_null> T/A ETag: <database_ETag>

Parameter Kueri

Firebase Database REST API menerima parameter dan nilai kueri berikut:

akses_token

Didukung oleh semua jenis permintaan. Mengautentikasi permintaan ini untuk mengizinkan akses ke data yang dilindungi oleh Aturan Keamanan Firebase Realtime Database. Lihat dokumentasi autentikasi REST untuk detailnya.

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

dangkal

Ini adalah fitur lanjutan yang dirancang untuk membantu Anda bekerja dengan kumpulan data besar tanpa perlu mengunduh semuanya. Setel ini ke true untuk membatasi kedalaman data yang dikembalikan di suatu lokasi. Jika data di lokasi adalah primitif JSON (string, angka, atau boolean), nilainya akan dikembalikan begitu saja. Jika cuplikan data di lokasi adalah objek JSON, nilai untuk setiap kunci akan dipotong menjadi true .

Argumen Metode REST Keterangan
dangkal MENDAPATKAN Batasi kedalaman respons.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Perhatikan bahwa shallow tidak dapat dicampur dengan parameter kueri lainnya.

mencetak

Memformat data yang dikembalikan sebagai respons dari server.

Argumen Metode REST Keterangan
cantik DAPATKAN, PUT, POST, PATCH, HAPUS Lihat data dalam format yang dapat dibaca manusia.
diam DAPATKAN, PUT, POST, PATCH Digunakan untuk menekan output dari server saat menulis data. Respons yang dihasilkan akan kosong dan ditandai dengan kode status HTTP 204 No Content .
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

panggilan balik

Hanya didukung oleh GET . Untuk melakukan panggilan REST dari browser web di seluruh domain, Anda dapat menggunakan JSONP untuk menggabungkan respons dalam fungsi panggilan balik JavaScript. Tambahkan callback= agar REST API membungkus data yang dikembalikan dalam fungsi panggilan balik yang Anda tentukan.

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

format

Jika disetel ke export , server akan mengkodekan prioritas dalam respons.

Argumen Metode REST Keterangan
ekspor MENDAPATKAN Sertakan informasi prioritas dalam respons.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

unduh

Hanya didukung oleh GET . Jika Anda ingin memicu pengunduhan file data Anda dari browser web, tambahkan download= . Hal ini menyebabkan layanan REST menambahkan header yang sesuai sehingga browser mengetahui cara menyimpan data ke file.

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

waktu habis

Gunakan ini untuk membatasi berapa lama waktu yang dibutuhkan untuk membaca di sisi server. Jika permintaan baca tidak selesai dalam waktu yang ditentukan, permintaan tersebut akan berakhir dengan kesalahan HTTP 400. Hal ini sangat berguna ketika Anda mengharapkan transfer data dalam jumlah kecil dan tidak ingin menunggu terlalu lama untuk mengambil subpohon yang berpotensi besar. Waktu baca sebenarnya mungkin bervariasi berdasarkan ukuran data dan cache.

Tentukan timeouts menggunakan format berikut: 3ms , 3s , atau 3min , dengan angka dan satuan. Jika tidak ditentukan, timeout maksimum 15min akan diterapkan. Jika timeout tidak positif, atau melebihi batas maksimum, permintaan akan ditolak dengan kesalahan HTTP 400.

tulisUkuranBatas

Untuk membatasi ukuran penulisan, Anda dapat menentukan parameter kueri writeSizeLimit sebagai tiny (target=1s), small (target=10s), medium (target=30s), large (target=60s). Realtime Database memperkirakan ukuran setiap permintaan tulis dan membatalkan permintaan yang akan memakan waktu lebih lama dari waktu target.

Jika Anda menentukan unlimited , penulisan yang sangat besar (dengan muatan hingga 256 MB) diperbolehkan, sehingga berpotensi memblokir permintaan berikutnya saat database memproses operasi saat ini. Penulisan tidak dapat dibatalkan setelah mencapai server.

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Anda akan melihat pesan kesalahan berikut jika tulisannya terlalu besar:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Selain itu, Anda dapat menyetel defaultWriteSizeLimit untuk seluruh instance database menggunakan Firebase CLI. Batasan ini berlaku untuk semua permintaan, termasuk permintaan dari SDK. Basis data baru dibuat dengan defaultWriteSizeLimit disetel ke large . Anda tidak dapat menyetel defaultWriteSizeLimit ke tiny menggunakan Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

dipesan oleh

Lihat bagian dalam panduan tentang data yang dipesan untuk informasi lebih lanjut.

limitToFirst, limitToLast, startAt, endAt, equalTo

Lihat bagian panduan tentang memfilter data untuk informasi lebih lanjut.

Streaming dari REST API

Titik akhir Firebase REST mendukung protokol EventSource/Server-Sent Events . Untuk mengalirkan perubahan ke satu lokasi di Realtime Database, Anda perlu melakukan beberapa hal:

  • Setel header Terima klien ke "text/event-stream"
  • Hormati Pengalihan HTTP, khususnya kode status HTTP 307
  • Jika lokasi memerlukan izin untuk membaca, Anda harus menyertakan parameter auth

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

event: event name
data: JSON encoded data payload

Server dapat mengirimkan peristiwa berikut:

meletakkan

Data yang dikodekan JSON adalah objek dengan dua kunci: path dan data . Kunci jalur menunjuk ke lokasi yang berhubungan dengan URL permintaan. Klien harus mengganti semua data di lokasi tersebut dalam cache dengan data .

tambalan

Data yang dikodekan JSON adalah objek dengan dua kunci: path dan data . Kunci jalur menunjuk ke lokasi yang berhubungan dengan URL permintaan. Untuk setiap kunci dalam data , klien harus mengganti kunci terkait dalam cache dengan data untuk kunci tersebut dalam pesan.

berusaha agar hidup

Data untuk acara ini adalah null . Tidak diperlukan tindakan apa pun.

membatalkan

Beberapa kesalahan tak terduga dapat mengirimkan acara `batal` dan mengakhiri koneksi. Penyebabnya dijelaskan dalam data yang disediakan untuk kejadian ini. Beberapa kemungkinan penyebabnya adalah sebagai berikut: 1. Aturan Keamanan Firebase Realtime Database tidak lagi mengizinkan pembacaan di lokasi yang diminta. Deskripsi `data` untuk penyebab ini adalah "Izin ditolak". 2. Penulisan memicu streamer peristiwa yang mengirimkan pohon JSON besar yang melebihi batas kami, 512 MB. `Data` untuk penyebab ini adalah "Muatan yang ditentukan terlalu besar, harap minta lokasi dengan data lebih sedikit."

auth_revoked

Data untuk peristiwa ini adalah string yang menunjukkan bahwa kredensial telah kedaluwarsa. Peristiwa ini dikirim ketika parameter auth yang diberikan tidak lagi valid.

Berikut ini contoh kumpulan peristiwa yang mungkin dikirimkan 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}}

Prioritas

Informasi prioritas suatu lokasi dapat direferensikan dengan "anak virtual" bernama .priority . Anda dapat membaca prioritas dengan permintaan GET dan menulisnya dengan permintaan PUT . Misalnya, permintaan berikut mengambil prioritas node users/tom :

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

Untuk menulis prioritas dan data secara bersamaan, Anda dapat menambahkan turunan .priority ke payload JSON:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

Untuk menulis prioritas dan nilai primitif (misalnya string) secara bersamaan, Anda dapat menambahkan turunan .priority dan memasukkan nilai primitif ke dalam turunan .value :

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

Ini menulis "Tom" dengan prioritas 1.0 . Prioritas dapat dimasukkan pada kedalaman apa pun dalam payload JSON.

Nilai Server

Anda dapat menulis nilai server di suatu lokasi menggunakan nilai placeholder yang merupakan objek dengan satu kunci .sv . Nilai untuk kunci tersebut adalah jenis nilai server yang ingin Anda tetapkan. Misalnya, permintaan berikut menetapkan nilai node ke stempel waktu server Firebase saat ini:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

Anda juga dapat menulis prioritas menggunakan nilai server, menggunakan jalur "anak virtual" yang disebutkan di atas.

Nilai server yang didukung meliputi:

Nilai Server
stempel waktu Waktu sejak zaman UNIX, dalam milidetik.
kenaikan Berikan nilai delta bilangan bulat atau floating point, dalam bentuk { ".sv": {"increment": <delta_value> }} , yang dapat digunakan untuk menaikkan nilai database saat ini secara atom. Jika data belum ada, pembaruan akan menyetel data ke nilai delta. Jika salah satu nilai delta atau data yang ada adalah angka floating point, kedua nilai tersebut akan diinterpretasikan sebagai angka floating point dan diterapkan di back-end sebagai nilai ganda. Aritmatika ganda dan representasi nilai ganda mengikuti semantik IEEE 754. Jika ada luapan bilangan bulat positif/negatif, jumlahnya dihitung sebagai ganda.

Mengambil dan Memperbarui Aturan Keamanan Firebase Realtime Database

REST API juga dapat digunakan untuk mengambil dan memperbarui Aturan Keamanan Firebase Realtime Database untuk proyek Firebase Anda. Anda memerlukan rahasia proyek Firebase, yang dapat Anda temukan di panel Akun Layanan pada setelan proyek Firebase Anda.

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Otentikasi permintaan

Secara default, permintaan REST dijalankan tanpa autentikasi dan hanya akan berhasil jika Aturan Realtime Database mengizinkan akses baca atau tulis publik ke data. Untuk mengautentikasi permintaan Anda, gunakan parameter kueri access_token= atau auth= .

Pelajari selengkapnya tentang autentikasi melalui REST API di Mengautentikasi Permintaan REST .

Kondisi Kesalahan

Firebase Database REST API dapat mengembalikan kode error berikut.

Kode Status HTTP
400 permintaan Buruk

Salah satu kondisi kesalahan berikut:

  • Tidak dapat mengurai data PUT atau POST .
  • Data PUT atau POST tidak ada.
  • Permintaan tersebut mencoba untuk PUT atau POST data yang terlalu besar.
  • Panggilan REST API berisi nama anak yang tidak valid sebagai bagian dari jalur.
  • Jalur panggilan REST API terlalu panjang.
  • Permintaan tersebut berisi nilai server yang tidak dikenal.
  • Indeks untuk kueri tidak ditentukan dalam Aturan Keamanan Firebase Realtime Database Anda.
  • Permintaan tidak mendukung salah satu parameter kueri yang ditentukan.
  • Permintaan tersebut menggabungkan parameter kueri dengan permintaan GET yang dangkal.
401 Tidak Sah

Salah satu kondisi kesalahan berikut:

404 tidak ditemukan Realtime Database yang ditentukan tidak ditemukan.
500 Internal Server Error Server mengembalikan kesalahan. Lihat pesan kesalahan untuk rincian lebih lanjut.
503 Layanan tidak tersedia Firebase Realtime Database yang ditentukan untuk sementara tidak tersedia, yang berarti permintaan tidak dilakukan.
412 Prasyarat Gagal Nilai ETag yang ditentukan permintaan di header if-match tidak cocok dengan nilai server.