Firebase Veritabanı REST API'si

API Kullanımı

Herhangi bir Firebase Gerçek Zamanlı Veritabanı URL'sini REST uç noktası olarak kullanabilirsiniz. Tek yapmanız gereken URL'nin sonuna .json eklemek ve favori HTTPS istemcinizden bir istek göndermek.

HTTPS gereklidir. Firebase, verilerinizin güvende kalması için yalnızca şifrelenmiş trafiğe yanıt verir.

GET - Veri Okuma

Gerçek Zamanlı Veritabanınızdaki veriler, bir uç noktaya HTTP GET isteği gönderilerek okunabilir. Aşağıdaki örnek, daha önce Realtime Database'de sakladığınız bir kullanıcının adını nasıl alabileceğinizi gösterir.

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

Başarılı bir istek, 200 OK HTTP durum koduyla gösterilir. Yanıt, GET isteğindeki yolla ilişkili verileri içerir.

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

PUT - Veri Yazma

PUT isteği ile veri yazabilirsiniz.

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

Başarılı bir istek, 200 OK HTTP durum koduyla gösterilir. Yanıt, PUT isteğinde belirtilen verileri içerir.

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

POST - Veri Aktarma

JavaScript push() yönteminin eşdeğerini gerçekleştirmek için (bkz. Veri Listeleri ), bir POST isteği gönderebilirsiniz.

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

Başarılı bir istek, 200 OK HTTP durum koduyla gösterilir. Yanıt, POST isteğinde belirtilen yeni verilerin alt adını içerir.

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

PATCH - Verileri Güncelleme

PATCH isteğini kullanarak mevcut verilerin üzerine yazmadan belirli bir konumdaki alt öğeleri güncelleyebilirsiniz. PATCH ile yazılan verilerde adı geçen çocukların üzerine yazılır ancak ihmal edilen çocuklar silinmez. Bu, JavaScript update() işlevine eşdeğerdir.

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

Başarılı bir istek, 200 OK HTTP durum koduyla gösterilir. Yanıt, PATCH isteğinde belirtilen verileri içerir.

{ "last": "Jones" }

SİL - Verileri Kaldırma

Bir DELETE isteğiyle verileri silebilirsiniz:

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

Başarılı bir DELETE isteği, JSON null içeren bir yanıtla birlikte 200 OK HTTP durum koduyla gösterilir.

Yöntemi Geçersiz Kılma

Önceki yöntemleri desteklemeyen bir tarayıcıdan REST çağrıları yapıyorsanız, bir POST isteği yaparak ve X-HTTP-Method-Override istek başlığını kullanarak yönteminizi ayarlayarak istek yöntemini geçersiz kılabilirsiniz.

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

Ayrıca x-http-method-override sorgu parametresini de kullanabilirsiniz.

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

Koşullu İstekler

SDK işlem işlemlerinin REST karşılığı olan koşullu istekler, verileri belirli bir koşula göre günceller. İş akışına genel bir bakışa bakın ve Verileri Kaydetme bölümünde REST için koşullu istekler hakkında daha fazla bilgi edinin.

Firebase ETag

Firebase ETag, belirli bir konumdaki mevcut veriler için benzersiz tanımlayıcıdır. Veriler bu konumda değişirse ETag da değişir. Firebase ETag, ilk REST isteğinin başlığında belirtilmelidir (genellikle bir GET , ancak PATCH dışında herhangi bir şey olabilir).

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

eğer eşleşirse

if-match koşulu, güncellemek istediğiniz verinin ETag değerini belirtir. Koşulu kullanırsanız, Gerçek Zamanlı Veritabanı yalnızca yazma isteğinde belirtilen ETag'in veritabanındaki mevcut verilerin ETag'iyle eşleştiği durumlarda istekleri tamamlar. ETag'i Firebase ETag isteği olan bir konuma getirin. Boş olan herhangi bir konumun üzerine yazmak istiyorsanız null_etag kullanın.

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

Beklenen yanıtlar

Aşağıdaki tabloda, ETag eşleşmesine göre her istek türü için beklenen yanıtlara genel bir bakış sunulmaktadır.

İstek Türü 'X-Firebase-ETag: doğru' ETag eşleşmeleri
if_match: <matching etag>		 ETag eşleşmiyor
if_match: <no matching etag>
ELDE ETMEK Yanıt Durumu/İçeriği 200: "<veri_at_yolu>" 400: "...desteklenmiyor.." 400: "...desteklenmiyor.."
Başlıklar eklendi ETag: <ETag_of_data> Yok Yok
KOYMAK Yanıt Durumu/İçeriği 200: "<girilen_veri>" 200: "<girilen_veri>" 412: "...ETag uyuşmazlığı.."
Başlıklar eklendi ETag: <ETag_of_put_data> Yok ETag: <database_ETag>
POSTALAMAK Yanıt Durumu/İçeriği 200: "<post_data>" 400: "...desteklenmiyor.." 400: "...desteklenmiyor.."
Başlıklar eklendi ETag: <ETag_of_post_data> Yok Yok
YAMA Yanıt Durumu/İçeriği 400: "...desteklenmiyor.." 400: "...desteklenmiyor.." 400: "...desteklenmiyor.."
Başlıklar eklendi Yok Yok Yok
SİLMEK Yanıt Durumu/İçeriği 200: boş 200: "<data_after_put>" 412: "...ETag uyuşmazlığı.."
Başlıklar eklendi ETag: <ETag_of_null> Yok ETag: <database_ETag>

Sorgu Parametreleri

Firebase Database REST API, aşağıdaki sorgu parametrelerini ve değerlerini kabul eder:

erişim_token

Tüm istek türleri tarafından desteklenir. Firebase Gerçek Zamanlı Veritabanı Güvenliği Kuralları tarafından korunan verilere erişime izin vermek için bu isteğin kimliğini doğrular. Ayrıntılar için REST kimlik doğrulama belgelerine bakın.

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

sığ

Bu, her şeyi indirmenize gerek kalmadan büyük veri kümeleriyle çalışmanıza yardımcı olmak için tasarlanmış gelişmiş bir özelliktir. Bir konumda döndürülen verilerin derinliğini sınırlamak için bunu true olarak ayarlayın. Konumdaki veriler bir JSON temel öğesiyse (dize, sayı veya boolean), değeri basitçe döndürülür. Konumdaki veri anlık görüntüsü bir JSON nesnesiyse her anahtarın değerleri true olarak kısaltılır.

Argümanlar REST Yöntemleri Tanım
sığ ELDE ETMEK Yanıtın derinliğini sınırlayın.
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

shallow parametrenin başka sorgu parametreleriyle karıştırılamayacağını unutmayın.

Yazdır

Sunucudan gelen yanıtta döndürülen verileri biçimlendirir.

Argümanlar REST Yöntemleri Tanım
tatlı AL, KOY, YAYINLA, YAMA, SİL Verileri insan tarafından okunabilir bir biçimde görüntüleyin.
sessiz AL, KOY, POST, YAMA Veri yazarken sunucudan gelen çıktıyı bastırmak için kullanılır. Ortaya çıkan yanıt boş olacak ve 204 No Content HTTP durum koduyla belirtilecektir.
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'

geri çağırmak

Yalnızca GET tarafından desteklenir. Bir web tarayıcısından etki alanları arasında REST çağrıları yapmak için, yanıtı bir JavaScript geri çağırma işlevine sarmak üzere JSONP'yi kullanabilirsiniz. REST API'nin döndürülen verileri belirttiğiniz geri çağırma işlevine sarmasını sağlamak için callback= ekleyin.

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

biçim

export olarak ayarlanırsa sunucu yanıttaki öncelikleri kodlayacaktır.

Argümanlar REST Yöntemleri Tanım
ihracat ELDE ETMEK Yanıta öncelik bilgisini ekleyin.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

indirmek

Yalnızca GET tarafından desteklenir. Verilerinizin bir web tarayıcısından dosya indirilmesini tetiklemek istiyorsanız download= ekleyin. Bu, tarayıcıların verileri bir dosyaya kaydetmesi gerektiğini bilmesi için REST hizmetinin uygun başlıkları eklemesine neden olur.

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

zaman aşımı

Sunucu tarafında okumanın ne kadar süreceğini sınırlamak için bunu kullanın. Okuma isteği ayrılan süre içinde tamamlanmazsa HTTP 400 hatasıyla sonlandırılır. Bu, özellikle küçük bir veri aktarımı beklediğinizde ve potansiyel olarak büyük bir alt ağaç getirmek için çok uzun süre beklemek istemediğinizde kullanışlıdır. Gerçek okuma süresi, veri boyutuna ve önbelleğe almaya bağlı olarak değişebilir.

timeouts şu biçimi kullanarak belirtin: 3ms , 3s veya 3min , bir sayı ve birimle birlikte. Belirtilmediği takdirde maksimum 15min timeout uygulanacaktır. timeout pozitif değilse veya maksimum değeri aşarsa istek, HTTP 400 hatasıyla reddedilir.

writeSizeLimit

Bir yazma işleminin boyutunu sınırlamak için writeSizeLimit sorgu parametresini tiny (target=1s), small (target=10s), medium (target=30s), large (target=60s) olarak belirtebilirsiniz. Gerçek Zamanlı Veritabanı, her yazma isteğinin boyutunu tahmin eder ve hedef süreden daha uzun sürecek istekleri iptal eder.

unlimited belirtirseniz olağanüstü büyük yazma işlemlerine (256 MB'a kadar yük ile) izin verilir; bu, veritabanı geçerli işlemi işlerken sonraki istekleri potansiyel olarak engelleyebilir. Yazma işlemleri sunucuya ulaştıktan sonra iptal edilemez.

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

Yazma çok büyükse aşağıdaki hata mesajını göreceksiniz:

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

Ayrıca Firebase CLI'yi kullanarak veritabanı örneğinin tamamı için defaultWriteSizeLimit değerini ayarlayabilirsiniz. Bu sınır, SDK'lardan gelenler de dahil olmak üzere tüm istekler için geçerlidir. Yeni veritabanları defaultWriteSizeLimit large olarak ayarlanarak oluşturulur. Firebase CLI'yi kullanarak defaultWriteSizeLimit tiny olarak ayarlayamazsınız.

firebase database:settings:set defaultWriteSizeLimit large

tarafından sipariş

Daha fazla bilgi için kılavuzun sıralı verilerle ilgili bölümüne bakın.

limitToFirst, limitToLast, startAt, endAt, equalTo

Daha fazla bilgi için kılavuzdaki verilerin filtrelenmesiyle ilgili bölüme bakın.

REST API'sinden akış

Firebase REST uç noktaları , EventSource/Sunucudan Gönderilen Olaylar protokolünü destekler. Değişiklikleri Gerçek Zamanlı Veritabanınızdaki tek bir konuma yayınlamak için birkaç şey yapmanız gerekir:

  • İstemcinin Accept başlığını "text/event-stream" olarak ayarlayın
  • HTTP Yönlendirmelerine, özellikle de HTTP durum kodu 307'ye saygı gösterin
  • Konum okuma izni gerektiriyorsa auth parametresini eklemelisiniz

Buna karşılık sunucu, istenen URL'deki verilerin durumu değiştikçe adlandırılmış olayları gönderecektir. Bu mesajların yapısı EventSource protokolüne uygundur.

event: event name
data: JSON encoded data payload

Sunucu aşağıdaki olayları gönderebilir:

koymak

JSON kodlu veriler iki anahtara sahip bir nesnedir: path ve data . Yol anahtarı, istek URL'sine göre bir konuma işaret eder. İstemci, önbelleğindeki bu konumdaki tüm verileri data ile değiştirmelidir.

yama

JSON kodlu veriler iki anahtara sahip bir nesnedir: path ve data . Yol anahtarı, istek URL'sine göre bir konuma işaret eder. data içindeki her anahtar için istemci, önbelleğindeki karşılık gelen anahtarı, mesajdaki o anahtarın verileriyle değiştirmelidir.

hayatta kal

Bu etkinliğe ilişkin veriler null . Hiçbir eylem gerekli değildir.

iptal etmek

Bazı beklenmeyen hatalar bir 'iptal' olayı gönderebilir ve bağlantıyı sonlandırabilir. Bunun nedeni, bu olay için sağlanan verilerde açıklanmaktadır. Bazı olası nedenler şunlardır: 1. Firebase Gerçek Zamanlı Veritabanı Güvenlik Kuralları artık istenen konumda okumaya izin vermiyor. Bu nedene ilişkin "veri" açıklaması "İzin reddedildi" şeklindedir. 2. Bir yazma işlemi, 512MB sınırımızı aşan büyük bir JSON ağacı gönderen bir olay aktarıcısını tetikledi. Bu nedene ilişkin 'veri' şu şekildedir: "Belirtilen yük çok büyük, lütfen daha az veri içeren bir konum isteyin."

auth_revoked

Bu etkinliğe ilişkin veriler, kimlik bilgisinin süresinin dolduğunu belirten bir dizedir. Bu olay, sağlanan auth parametresi artık geçerli olmadığında gönderilir.

Sunucunun gönderebileceği örnek bir olay kümesi aşağıda verilmiştir:

// 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}}

Öncelikler

Bir konuma ilişkin öncelik bilgilerine .priority adlı bir "sanal alt öğe" ile başvurulabilir. GET istekleriyle öncelikleri okuyabilir ve PUT istekleriyle yazabilirsiniz. Örneğin, aşağıdaki istek users/tom düğümünün önceliğini alır:

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

Önceliği ve verileri aynı anda yazmak için JSON yüküne bir .priority alt öğesi ekleyebilirsiniz:

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

Önceliği ve temel değeri (örneğin bir dize) aynı anda yazmak için, bir .priority alt öğesi ekleyebilir ve ilkel değeri bir .value alt öğesine yerleştirebilirsiniz:

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

Bu, "Tom" u 1.0 önceliğiyle yazar. Öncelikler, JSON yükünün herhangi bir derinliğine dahil edilebilir.

Sunucu Değerleri

Tek bir .sv anahtarına sahip bir nesne olan yer tutucu değeri kullanarak bir konumdaki sunucu değerlerini yazabilirsiniz. Bu anahtarın değeri, ayarlamak istediğiniz sunucu değerinin türüdür. Örneğin, aşağıdaki istek, düğümün değerini Firebase sunucusunun geçerli zaman damgasına ayarlar:

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

Yukarıda belirtilen "sanal alt" yolu kullanarak sunucu değerlerini kullanarak öncelikleri de yazabilirsiniz.

Desteklenen sunucu değerleri şunları içerir:

Sunucu Değeri
zaman damgası UNIX döneminden bu yana geçen süre, milisaniye cinsinden.
artış Geçerli veritabanı değerinin atomik olarak artırılacağı { ".sv": {"increment": <delta_value> }} biçiminde bir tamsayı veya kayan noktalı delta değeri sağlayın. Veriler henüz mevcut değilse güncelleme, verileri delta değerine ayarlayacaktır. Delta değerlerinden herhangi biri veya mevcut veriler kayan noktalı sayılar ise, her iki değer de kayan noktalı sayılar olarak yorumlanacak ve arka uçta double değer olarak uygulanacaktır. Çift aritmetik ve çift değerlerin gösterimi IEEE 754 semantiğini takip eder. Pozitif/negatif tamsayı taşması varsa toplam double olarak hesaplanır.

Firebase Gerçek Zamanlı Veritabanı Güvenliği Kurallarını Alma ve Güncelleme

REST API, Firebase projeniz için Firebase Gerçek Zamanlı Veritabanı Güvenlik Kurallarını almak ve güncellemek için de kullanılabilir. Firebase projenizin ayarındaki Hizmet Hesapları paneli altında bulabileceğiniz Firebase projenizin sırrına ihtiyacınız olacak.

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'

İstekleri doğrula

Varsayılan olarak, REST istekleri kimlik doğrulaması olmadan yürütülür ve yalnızca Gerçek Zamanlı Veritabanı Kurallarının verilere genel okuma veya yazma erişimine izin vermesi durumunda başarılı olur. İsteğinizin kimliğini doğrulamak için access_token= veya auth= sorgu parametrelerini kullanın.

REST İsteklerini Doğrulama bölümünde REST API aracılığıyla kimlik doğrulama hakkında daha fazla bilgi edinin.

Hata Koşulları

Firebase Database REST API aşağıdaki hata kodlarını döndürebilir.

HTTP Durum Kodları
400 Hatalı İstek

Aşağıdaki hata koşullarından biri:

  • PUT veya POST verileri ayrıştırılamıyor.
  • PUT veya POST verileri eksik.
  • İstek, çok büyük olan PUT veya POST verilerini denemeye çalışıyor.
  • REST API çağrısı, yolun parçası olarak geçersiz alt adlar içeriyor.
  • REST API çağrı yolu çok uzun.
  • İstek tanınmayan bir sunucu değeri içeriyor.
  • Sorgunun dizini Firebase Gerçek Zamanlı Veritabanı Güvenliği Kurallarınızda tanımlı değil.
  • İstek, belirtilen sorgu parametrelerinden birini desteklemiyor.
  • İstek, sorgu parametrelerini sığ bir GET isteğiyle karıştırır.
401 Yetkisiz

Aşağıdaki hata koşullarından biri:

404 Bulunamadı Belirtilen Gerçek Zamanlı Veritabanı bulunamadı.
500 Dahili Sunucu Hatası Sunucu bir hata döndürdü. Daha fazla ayrıntı için hata mesajına bakın.
503 Hizmet Kullanılamıyor Belirtilen Firebase Gerçek Zamanlı Veritabanı geçici olarak kullanılamıyor; bu, isteğin denenmediği anlamına gelir.
412 Önkoşul Başarısız İsteğin if-match başlığında belirtilen ETag değeri sunucunun değeriyle eşleşmedi.