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şmeleriif_match: <matching etag> | ETag eşleşmiyorif_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:
|
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. |
Aksi belirtilmediği sürece bu sayfanın içeriği Creative Commons Atıf 4.0 Lisansı altında ve kod örnekleri Apache 2.0 Lisansı altında lisanslanmıştır. Ayrıntılı bilgi için Google Developers Site Politikaları'na göz atın. Java, Oracle ve/veya satış ortaklarının tescilli ticari markasıdır.
Son güncelleme tarihi: 2024-03-20 UTC.