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 ETagif_match: <matching etag> | ETag tidak cocokif_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:
|
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. |
Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.
Terakhir diperbarui pada 2024-03-20 UTC.