REST API Firebase Database

Penggunaan API

Anda dapat menggunakan URL Firebase Realtime Database sebagai endpoint REST. Yang Anda perlukan untuk adalah menambahkan .json ke akhir URL dan mengirim permintaan dari klien HTTPS favorit Anda.

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

Anda dapat memilih region untuk membuat instance Realtime Database. Pilihan wilayah memengaruhi URL {i>database<i}. Contoh di halaman ini adalah untuk wilayah us-central1, dengan Skema URL <dbname>.firebaseio.com. Untuk wilayah dan URL yang saat ini didukung skema kustom, lihat topik panduan tentang memilih lokasi di project Firebase.

GET - Membaca Data

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

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

Dalam contoh di halaman ini, Anda akan mengganti [PROJECT_ID] dengan ID project Firebase Anda.

Permintaan yang berhasil ditunjukkan dengan HTTP 200 OK kode status. Respons 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 HTTP 200 OK kode status. Respons berisi data yang ditentukan dalam Permintaan PUT.

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

POST - Mendorong Data

Untuk mencapai nilai yang setara dengan push() JavaScript (lihat Daftar Data), Anda dapat mengirimkan permintaan POST.

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

Permintaan yang berhasil ditunjukkan dengan status HTTP 200 OK pada kode sumber. Respons 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 file data yang ada menggunakan permintaan PATCH. Anak-anak yang disebutkan di data yang ditulis dengan PATCH akan ditimpa, tetapi dihilangkan turunan tidak dihapus. Fungsi ini sama dengan JavaScript Fungsi update().

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

Permintaan yang berhasil ditunjukkan dengan status HTTP 200 OK pada kode sumber. Respons berisi data yang ditentukan dalam Permintaan PATCH.

{ "last": "Jones" }

DELETE - 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 bisa mengganti metode permintaan dengan membuat Permintaan POST dan setelan 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, REST yang setara dengan operasi transaksi SDK, memperbarui data sesuai dengan kondisi tertentu. Lihat ringkasan alur kerja dan pelajari permintaan bersyarat lebih lanjut untuk REST di Menyimpan Data.

ETag Firebase

Firebase ETag adalah ID unik untuk data saat ini di lokasi yang ditentukan. Jika perubahan data di lokasi itu, ETag juga akan berubah. ETag Firebase harus ditentukan dalam untuk permintaan REST awal (biasanya GET, tetapi dapat berupa apa pun selain PATCH).

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

if-match

Kondisi if-match menentukan nilai ETag untuk data yang ingin diperbarui. Jika Anda menggunakan kondisi ini, Realtime Database hanya akan menyelesaikan permintaan ketika ETag yang ditentukan dalam sesuai dengan ETag data yang ada dalam database. Ambil ETag di lokasi dengan permintaan ETag Firebase. Jika Anda ingin menimpa lokasi apa 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]'

Respons yang diharapkan

Tabel berikut memberikan ringkasan respons yang diharapkan untuk setiap jenis permintaan, berdasarkan pencocokan ETag.

Jenis Permintaan		'X-Firebase-ETag: true'	ETag cocok dengan if_match: <matching etag>	ETag tidak sesuai dengan if_match: <no matching etag>
DAPATKAN	Status/Konten Respons	200: "<data_at_path>"	400: "...tidak didukung.."	400: "...tidak didukung.."
	Header yang Ditambahkan	ETag: <ETag_of_data>	T/A	T/A
PUT	Status/Konten Respons	200: "<put_data>"	200: "<put_data>"	412: "...ETag tidak cocok.."
	Header yang Ditambahkan	ETag: <ETag_of_put_data>	T/A	ETag: <database_ETag>
SESUDAH	Status/Konten Respons	200: "<post_data>"	400: "...tidak didukung.."	400: "...tidak didukung.."
	Header yang Ditambahkan	ETag: <ETag_of_post_data>	T/A	T/A
PATCH	Status/Konten Respons	400: "...tidak didukung.."	400: "...tidak didukung.."	400: "...tidak didukung.."
	Header yang Ditambahkan	T/A	T/A	T/A
HAPUS	Status/Konten Respons	200: null	200: "<data_after_put>"	412: "...ETag tidak cocok.."
	Header yang Ditambahkan	ETag: <ETag_of_null>	T/A	ETag: <database_ETag>

Parameter Kueri

Firebase Database REST API menerima parameter kueri berikut dan nilai-nilai:

access_token

Didukung oleh semua jenis permintaan. Mengautentikasi permintaan ini untuk mengizinkan akses ke data yang dilindungi oleh Firebase Realtime Database Security Rules. Lihat Dokumentasi autentikasi REST untuk mengetahui detailnya.

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

shallow

Ini adalah fitur lanjutan, yang dirancang untuk membantu Anda bekerja dengan {i>dataset<i} tanpa perlu mengunduh semuanya. Tetapkan ini ke true untuk membatasi kedalaman data yang ditampilkan di suatu lokasi. Jika data di lokasi tersebut adalah dasar JSON (string, angka, atau boolean), nilainya hanya akan dikembalikan. Jika snapshot data di lokasi tersebut adalah objek JSON, untuk setiap kunci akan dipangkas menjadi true.

Argumen	Metode REST	Deskripsi
dangkal	DAPATKAN	Batasi kedalaman respons.

curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Perlu diketahui bahwa shallow tidak dapat digabungkan dengan kueri lainnya parameter.

print

Memformat data yang ditampilkan dalam respons dari server.

Argumen	Metode REST	Deskripsi
sangat	GET, PUT, POST, PATCH, DELETE	Melihat data dalam format yang dapat dibaca manusia.
senyap	GET, PUT, POST, PATCH	Digunakan untuk menyembunyikan output dari server saat menulis data. Respons yang dihasilkan akan kosong dan ditunjukkan oleh 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'

callback

Hanya didukung oleh GET. Untuk melakukan panggilan REST dari browser web di seluruh domain, Anda dapat menggunakan JSONP untuk menggabungkan respons dalam JavaScript fungsi callback. Tambahkan callback= untuk menggabungkan REST API data yang ditampilkan dalam fungsi callback 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 mengenkode prioritas di yang dihasilkan.

Argumen	Metode REST	Deskripsi
ekspor	DAPATKAN	Sertakan informasi prioritas dalam respons.

curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

download

Hanya didukung oleh GET. Jika Anda ingin memicu file mendownload data Anda dari browser web, tambahkan download=. Hal ini menyebabkan layanan REST menambahkan header yang sesuai sehingga {i>browser<i} tahu cara menyimpan data ke dalam file.

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

Pencadangan Pribadi: Kami tidak menyarankan penggunaan REST API untuk mencadangkan Realtime Database. Sebagai gantinya, siapkan Firebase Pencadangan Pribadi.

timeout

Gunakan ini untuk membatasi waktu baca yang dibutuhkan di sisi server. Jika pembacaan tidak selesai dalam waktu yang ditentukan, permintaan akan diakhiri dengan permintaan error 400. Ini sangat berguna ketika Anda mengharapkan pengiriman data berukuran kecil dan tidak ingin menunggu terlalu lama untuk mengambil subpohon yang mungkin berukuran besar. Aktual waktu baca dapat bervariasi berdasarkan ukuran data dan penyimpanan dalam cache.

Tentukan timeouts menggunakan format berikut: 3ms, 3s, atau 3min, dengan angka dan satuan. Jika tidak ditentukan, maksimum timeout dari 15min akan diterapkan. Jika timeout tidak positif, atau melebihi nilai maksimum, permintaan akan ditolak dengan pesan {i>error<i} HTTP 400.

writeSizeLimit

Catatan: Parameter ini berlaku untuk operasi hapus dan tulis.

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

Jika Anda menentukan unlimited, operasi tulis yang sangat besar (dengan payload hingga 256 MB) diizinkan, yang berpotensi memblokir permintaan berikutnya saat database memproses operasi saat ini. Operasi tulis tidak dapat dibatalkan setelah sampai ke server.

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

Anda akan melihat pesan error berikut jika tulisan 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 menetapkan defaultWriteSizeLimit untuk seluruh database menggunakan Firebase CLI. Batas ini berlaku untuk semua permintaan, termasuk permintaan dari SDK. Database baru dibuat dengan defaultWriteSizeLimitditetapkan ke large. Anda tidak dapat menetapkan defaultWriteSizeLimit ke tiny menggunakan Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

Penghapusan besar yang disengaja: Untuk menghapus node besar, pertimbangkan untuk menggunakan Firebase CLI, yang dengan baik melakukan penghapusan terpotong. Penghapusan besar melalui klien atau Admin SDK dapat memblokir database Anda hingga penghapusan selesai.

firebase database:remove /large/path/to/delete

Lihat postingan blog ini untuk mengetahui informasi selengkapnya.

orderBy

Lihat bagian dalam panduan tentang data yang dipesan untuk informasi selengkapnya.

limitToFirst, limitToLast, startAt, endAt, equalTo

Lihat bagian dalam panduan tentang memfilter data untuk informasi selengkapnya.

Streaming dari REST API

Endpoint Firebase REST mendukung EventSource / Peristiwa Terkirim Server dan berperforma tinggi karena merupakan protokol biner. Untuk mengalirkan perubahan ke satu lokasi di Realtime Database, Anda perlu melakukan beberapa hal:

• Tetapkan header Accept klien ke "text/event-stream"
• Patuhi Pengalihan HTTP, terutama kode status HTTP 307
• Jika lokasi memerlukan izin untuk membaca, Anda harus menyertakan Parameter auth

Sebagai balasannya, server akan mengirimkan kejadian 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 mengirimkan kejadian berikut:

put

Data yang dienkode JSON adalah objek dengan dua kunci: path dan data. path menunjukkan sesuai dengan URL permintaan. Klien harus mengganti semua data di lokasi tersebut dalam cache dengan data.

patch

Data yang dienkode JSON adalah objek dengan dua kunci: path dan data. path menunjukkan sesuai dengan URL permintaan. Untuk setiap kunci di 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. Anda tidak perlu melakukan tindakan apa pun.

batal

Beberapa error tak terduga dapat mengirim peristiwa `cancel` dan menghentikan koneksi. Penyebabnya dijelaskan dalam data yang diberikan untuk peristiwa ini. Beberapa kemungkinan penyebabnya adalah berikut ini: Akun Layanan 1. Firebase Realtime Database Security Rules tidak lagi mengizinkan pembacaan di lokasi yang diminta. Tujuan Deskripsi `data` untuk penyebab ini adalah "Izin ditolak". 2. Penulisan memicu streamer peristiwa yang mengirim hierarki JSON besar yang melebihi batas, 512MB. `Data` untuk penyebab ini adalah "Payload yang ditentukan terlalu besar, minta dengan lebih sedikit data."

auth_revoked

Data untuk peristiwa ini adalah string yang menunjukkan bahwa kredensial masa berlakunya telah berakhir. Peristiwa ini dikirim saat auth yang disediakan tidak lagi valid.

Berikut adalah contoh rangkaian peristiwa yang mungkin dikirim 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 untuk lokasi dapat direferensikan dengan "anak virtual" bernama .priority. Anda dapat membaca prioritas dengan GET permintaan dan tulis 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 .priority turunan 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 dalam turunan .value:

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

Perintah ini menulis "Tom" dengan prioritas 1.0. Prioritas dapat disertakan pada kedalaman berapa pun dalam payload JSON.

Nilai Server

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

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

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

Nilai server yang didukung meliputi:

Nilai Server
stempel waktu	Waktu sejak epoch UNIX, dalam milidetik.
inkremental	Berikan nilai delta bilangan bulat atau floating point, dalam bentuk { ".sv": {"increment": <delta_value> }}, yang akan digunakan secara atomik menambah nilai {i>database<i} saat ini. Jika data belum ada, pembaruan akan disetel data ke nilai delta. Jika salah satu nilai delta atau data yang ada mengambang tersebut, kedua nilai akan ditafsirkan sebagai angka floating point dan diterapkan pada {i>back-end<i} sebagai nilai ganda. Aritmatika ganda dan representasi dari nilai ganda mengikuti Semantik IEEE 754. Jika ada luapan bilangan bulat positif/negatif, jumlah akan dihitung sebagai {i>double<i}.

Mengambil dan Memperbarui Firebase Realtime Database Security Rules

REST API juga dapat digunakan untuk mengambil Firebase Realtime Database Security Rules untuk project Firebase Anda. Anda akan memerlukan rahasia proyek Firebase, yang yang dapat ditemukan pada Panel Service Accounts di project Firebase deskripsi tempat.

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'

Mengautentikasi permintaan

Secara {i>default<i}, permintaan REST dijalankan tanpa otentikasi dan hanya akan berhasil jika Realtime Database Aturan mengizinkan akses baca atau tulis publik ke yang mengupload data. Untuk mengautentikasi permintaan Anda, gunakan Parameter kueri access_token= atau auth=.

Pelajari lebih lanjut autentikasi melalui REST API di Mengautentikasi Permintaan REST.

Kondisi Error

REST API Firebase Database dapat menampilkan kode error berikut.

Kode Status HTTP
400 Permintaan Tidak Valid	Salah satu kondisi error berikut: Tidak dapat mengurai data PUT atau POST. Data PUT atau POST tidak ada. Permintaan mencoba PUT atau POST data yang terlalu besar. Panggilan REST API berisi nama turunan yang tidak valid sebagai bagian dari jalur. Jalur panggilan REST API terlalu panjang. Permintaan berisi nilai server yang tidak dikenal. Indeks kueri tidak didefinisikan dalam Firebase Realtime Database Security Rules Permintaan tidak mendukung salah satu parameter kueri yang ditentukan. Permintaan mencampur parameter kueri dengan permintaan GET yang dangkal.
401 Tidak Sah	Salah satu kondisi error berikut: Masa berlaku token autentikasi telah berakhir. Token autentikasi yang digunakan dalam permintaan tidak valid. Gagal mengautentikasi dengan access_token. Permintaan tersebut melanggar Firebase Realtime Database Security Rules
404 Tidak Ditemukan	Realtime Database yang ditentukan tidak ditemukan.
500 Error Server Internal	Server menampilkan error. Lihat pesan error untuk informasi lebih lanjut spesifikasi pendukung.
503 Layanan Tidak Tersedia	Firebase Realtime Database yang ditentukan untuk sementara tidak tersedia, yang berarti permintaan tidak dicoba.
412 Prekondisi Gagal	Nilai ETag yang ditentukan dalam permintaan di header if-match tidak sesuai dengan nilai server.