Bu belgede, veri almayla ilgili temel bilgilerin yanı sıra Firebase verilerinin nasıl sıralanacağı ve filtreleneceği açıklanmaktadır.
Başlamadan önce
Uygulamanızı kurduğunuzdan ve Get Started
kılavuzunda açıklandığı şekilde veritabanına erişebildiğinizden emin olun.
Veri Alma
Firebase verileri, GetValue()
için tek seferlik çağrı yapılarak veya FirebaseDatabase
referansında ValueListener
öğesine eklenerek alınır. Değer işleyici bir kez verilerin ilk durumu için ve veriler her değiştiğinde bir kez daha çağrılır.
Veritabanı Referansı Alma
Veritabanı'na veri yazmak için DatabaseReference
örneğinin olması gerekir:
// Get the root reference location of the database. firebase::database::DatabaseReference dbref = database->GetReference();
Verileri bir kez oku
Belirli bir yoldaki içeriklerin statik anlık görüntüsünü bir kez okumak için GetValue()
yöntemini kullanabilirsiniz. Görev sonucu, alt veriler de dahil olmak üzere söz konusu konumdaki tüm verileri içeren bir anlık görüntü içerir. Veri yoksa döndürülen anlık görüntü null
olur.
firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("Leaders").GetValue();
Talep yapılmış olsa da değeri okuyabilmek için Geleceğin tamamlanmasını beklememiz gerekiyor. Oyunlar genellikle bir döngüde çalıştığından ve diğer uygulamalardan daha az geri çağırmaya yönlendirdiğinden genellikle tamamlanmak için yoklama yaparsınız.
// In the game loop that polls for the result... if (result.status() != firebase::kFutureStatusPending) { if (result.status() != firebase::kFutureStatusComplete) { LogMessage("ERROR: GetValue() returned an invalid result."); // Handle the error... } else if (result.error() != firebase::database::kErrorNone) { LogMessage("ERROR: GetValue() returned error %d: %s", result.error(), result.error_message()); // Handle the error... } else { firebase::database::DataSnapshot snapshot = result.result(); // Do something with the snapshot... } }
Burada bazı temel hata kontrolleri gösterilir. Hata kontrolü ve sonucun ne zaman hazır olduğunu belirleme yöntemleri hakkında daha fazla bilgi için firebase::Future referansını inceleyin.
Etkinlikleri dinleyin
Verilerde yapılan değişikliklere abone olacak dinleyiciler ekleyebilirsiniz:
ValueListener
temel sınıf
Geri çağırma | Tipik kullanım |
---|---|
OnValueChanged |
Bir yolun tüm içeriğindeki değişiklikleri okuma ve dinleme. |
OnChildListener
temel sınıf
OnChildAdded
| Öğe listelerini alın veya öğe listesine yapılan eklemeleri dinleyin.
Listelerde yapılan değişiklikleri izlemek için OnChildChanged ve OnChildRemoved ile kullanılması önerilir. |
OnChildChanged |
Listedeki öğelerde yapılan değişiklikleri bekleyin. Listelerde yapılan değişiklikleri izlemek için OnChildAdded ve OnChildRemoved ile birlikte kullanın. |
OnChildRemoved |
Bir listeden kaldırılan öğeleri bekleyin. Listelerde yapılan değişiklikleri izlemek için OnChildAdded ve OnChildChanged ile birlikte kullanın. |
OnChildMoved |
Sıralı listedeki öğelerin sırasındaki değişiklikleri bekleyin.
OnChildMoved geri çağırmaları, öğenin sırası değiştiğinden (mevcut sipariş yönteminize göre) her zaman OnChildChanged geri çağırmasını takip eder. |
ValueListener sınıfı
Belirli bir yoldaki içeriklerde yapılan değişikliklere abone olmak için OnValueChanged
geri çağırmalarını kullanabilirsiniz. Bu geri çağırma, işleyici eklendiğinde bir kez ve alt öğeler dahil olmak üzere veriler her değiştiğinde tekrar tetiklenir. Geri çağırma, alt veriler de dahil olmak üzere söz konusu konumdaki tüm verileri içeren bir anlık görüntü iletir. Veri yoksa döndürülen anlık görüntü null
olur.
Aşağıdaki örnekte, veritabanından bir skor tablosunun skorlarını alan bir oyun gösterilmektedir:
class LeadersValueListener : public firebase::database::ValueListener { public: void OnValueChanged( const firebase::database::DataSnapshot& snapshot) override { // Do something with the data in snapshot... } void OnCancelled(const firebase::database::Error& error_code, const char* error_message) override { LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code, error_message); } }; // Elsewhere in the code... LeadersValueListener* listener = new LeadersValueListener(); firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("Leaders").AddValueListener(listener);
Future<DataSnapshot>
sonucu, etkinlik sırasında veritabanında belirtilen konumda bulunan verileri içerir. Anlık görüntüde value()
çağrısı yapıldığında verileri temsil eden bir Variant
döndürülür.
Bu örnekte, okuma işleminin iptal edilip edilmediğini görmek için OnCancelled
yöntemi de geçersiz kılınır. Örneğin, istemcinin bir Firebase veritabanı konumundan okuma izni yoksa okuma işlemi iptal edilebilir. database::Error
, hatanın neden oluştuğunu belirtir.
ChildListener sınıfı
Alt etkinlikler, PushChild()
yöntemiyle eklenen yeni bir alt öğe veya UpdateChildren()
yöntemiyle güncellenen bir alt öğe gibi bir işlemdeki düğümün alt öğelerine yapılan belirli işlemlere yanıt olarak tetiklenir. Bunların her biri, veritabanındaki belirli bir düğümde yapılan değişiklikleri dinlemek için faydalı olabilir. Örneğin, bir oyun aşağıda gösterildiği gibi bir oyun oturumunun yorumlarındaki etkinliği izlemek için bu yöntemleri birlikte kullanabilir:
class SessionCommentsChildListener : public firebase::database::ChildListener { public: void OnChildAdded(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnChildChanged(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnChildRemoved( const firebase::database::DataSnapshot& snapshot) override { // Do something with the data in snapshot ... } void OnChildMoved(const firebase::database::DataSnapshot& snapshot, const char* previous_sibling) override { // Do something with the data in snapshot ... } void OnCancelled(const firebase::database::Error& error_code, const char* error_message) override { LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s", error_code, error_message); } }; // elsewhere .... SessionCommentsChildListener* listener = new SessionCommentsChildListener(); firebase::Future<firebase::database::DataSnapshot> result = dbRef.GetReference("GameSessionComments").AddChildListener(listener);
OnChildAdded
geri çağırması genellikle Firebase veritabanındaki öğelerin listesini almak için kullanılır. OnChildAdded
geri çağırması, mevcut her alt öğe için bir kez ve belirtilen yola her yeni alt öğe eklendiğinde tekrar çağrılır. İşleyiciye, yeni alt öğenin verilerini içeren bir anlık görüntü iletilir.
Bir alt düğüm her değiştirildiğinde OnChildChanged
geri çağırması çağrılır.
Buna alt düğümün alt öğelerinde yapılan değişiklikler de dahildir. Genellikle bir öğe listesindeki değişikliklere yanıt vermek için OnChildAdded
ve OnChildRemoved
çağrılarıyla birlikte kullanılır. İşleyiciye iletilen anlık görüntü, alt öğe için güncellenmiş verileri içerir.
Şundan birincisi kaldırıldığında OnChildRemoved
geri çağırması tetiklenir.
Genellikle OnChildAdded
ve OnChildChanged
geri çağırmalarıyla birlikte kullanılır. Geri çağırmaya iletilen anlık görüntü, kaldırılan alt öğenin verilerini içerir.
OnChildChanged
çağrısı, alt öğenin yeniden sıralanmasına neden olan bir güncelleme tarafından gerçekleştirildiğinde OnChildMoved
geri çağırması tetiklenir. OrderByChild
veya OrderByValue
ile sıralanmış verilerle kullanılır.
Verileri sıralama ve filtreleme
Verileri anahtara, değere veya bir alt öğenin değerine göre sıralanmış şekilde almak için Realtime Database Query
sınıfını kullanabilirsiniz. Sıralanan sonucu belirli sayıda sonuç veya anahtar ya da değer aralığına göre de filtreleyebilirsiniz.
Verileri sırala
Sıralanmış verileri almak için öncelikle sonuçların nasıl sıralandığını belirlemek üzere sıralama yöntemlerinden birini belirtin:
Yöntem | Kullanım |
---|---|
OrderByChild() |
Sonuçları, belirtilen bir alt anahtarın değerine göre sıralayın. |
OrderByKey()
| Sonuçları alt anahtarlara göre sıralayın. |
OrderByValue() |
Sonuçları alt değerlere göre sıralayın. |
Aynı anda yalnızca bir sıralama yöntemi kullanabilirsiniz. Bir sıralama yönteminin aynı sorguda birden çok kez çağrılması hataya neden olur.
Aşağıdaki örnek, skora göre sıralanmış bir skor tablosuna nasıl abone olabileceğinizi gösterir.
firebase::database::Query query = dbRef.GetReference("Leaders").OrderByChild("score"); // To get the resulting DataSnapshot either use query.GetValue() and poll the // future, or use query.AddValueListener() and register to handle the // OnValueChanged callback.
Bu, bir ValueListener ile birleştirildiğinde istemciyi veritabanındaki leaderboard ile senkronize eden bir firebase::Query
tanımlar. Bu sıralama, her girişin puanına göre sıralanır.
Veritabanınızı Yapılandırma bölümünde verilerinizi verimli bir şekilde yapılandırma hakkında daha fazla bilgi edinebilirsiniz.
OrderByChild()
yöntemine yapılan çağrı, sonuçların sıralanacağı alt anahtarı belirtir. Bu durumda sonuçlar, her bir alt öğedeki "score"
değerine göre sıralanır. Diğer veri türlerinin nasıl sıralandığı hakkında daha fazla bilgi için Sorgu verileri nasıl sıralanır? bölümüne bakın.
Veri filtreleme
Verileri filtrelemek için bir sorgu oluştururken sınır veya aralık yöntemlerinden herhangi birini tek bir sıralama yöntemiyle birleştirebilirsiniz.
Yöntem | Kullanım |
---|---|
LimitToFirst() |
Sıralı sonuç listesinin başlangıcından itibaren döndürülecek maksimum öğe sayısını ayarlar. |
LimitToLast() |
Sıralı sonuç listesinin sonundan döndürülecek maksimum öğe sayısını ayarlar. |
StartAt() |
Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtar veya değerden büyük veya ona eşit olan öğeleri döndürün. |
EndAt() |
Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtar veya değerden düşük veya ona eşit olan öğeleri döndürün. |
EqualTo() |
Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtar veya değere eşit olan öğeleri döndürün. |
Sıralama ölçütü yöntemlerinden farklı olarak birden çok sınırlama veya aralık işlevini birleştirebilirsiniz.
Örneğin, sonuçları belirli bir değer aralığıyla sınırlamak için StartAt()
ve EndAt()
yöntemlerini birleştirebilirsiniz.
Sorgu için tek bir eşleşme olsa bile anlık görüntü yine de bir listedir ve yalnızca tek bir öğe içerir.
Sonuç sayısını sınırlandırın
Belirli bir geri çağırma işlemi için senkronize edilecek maksimum alt öğe sayısını ayarlamak için LimitToFirst()
ve LimitToLast()
yöntemlerini kullanabilirsiniz. Örneğin, 100 sınır belirlemek için LimitToFirst()
kullanırsanız başlangıçta en fazla 100 OnChildAdded
geri çağırması alırsınız. Firebase veritabanınızda depolanan öğe sayısı 100'den azsa her öğe için OnChildAdded
geri çağırması etkinleşir.
Öğeler değiştikçe sorguya giren öğeler için OnChildAdded
geri çağırma, sorgudan çıkan öğeler için ise OnChildRemoved
geri çağırma alırsınız. Böylece toplam sayı 100'de kalır.
Örneğin, aşağıdaki kod, bir leaderboard'daki en yüksek skoru döndürür:
firebase::database::Query query = dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1); // To get the resulting DataSnapshot either use query.GetValue() and poll the // future, or use query.AddValueListener() and register to handle the // OnValueChanged callback.
Anahtar veya değere göre filtreleyin
Sorgular için rastgele başlangıç, bitiş ve denklik noktalarını seçmek isterseniz StartAt()
, EndAt()
ve EqualTo()
kullanabilirsiniz. Bu, verileri sayfalara ayırmak veya belirli bir değere sahip alt öğeleri olan öğeleri bulmak için yararlı olabilir.
Sorgu verileri nasıl sıralanır?
Bu bölümde, verilerin Query
sınıfındaki her bir yönteme göre nasıl sıralandığı açıklanmaktadır.
OrderByChild
OrderByChild()
kullanılırken belirtilen alt anahtarı içeren veriler aşağıdaki gibi sıralanır:
- Belirtilen alt anahtarda
null
değerine sahip olan alt öğeler önce gelir. - Belirtilen alt anahtar için
false
değerine sahip olan alt öğeler ardından gelir. Birden fazla alt öğefalse
değerine sahipse bunlar anahtara göre sözlüksel olarak sıralanır. - Belirtilen alt anahtar için
true
değerine sahip olan alt öğeler ardından gelir. Birden fazla alt öğetrue
değerine sahipse bunlar sözlüksel olarak anahtara göre sıralanır. - Sayısal değere sahip olan alt öğeler artan düzende sıralanır. Belirtilen alt düğüm için aynı sayısal değere sahip birden fazla alt öğe varsa bunlar anahtara göre sıralanır.
- Dizeler sayılardan sonra gelir ve sözlüksel olarak artan düzende sıralanır. Birden fazla alt düğüm, belirtilen alt düğüm için aynı değere sahipse bunlar sözlüksel olarak anahtara göre sıralanır.
- Nesneler son sırada gelir ve anahtara göre sözlüksel olarak artan düzende sıralanır.
OrderByKey
Verilerinizi sıralamak için OrderByKey()
kullandığınızda veriler, anahtara göre artan düzende döndürülür.
- 32 bit tam sayı olarak ayrıştırılabilen bir anahtarı olan alt öğeler önce gelir ve artan düzende sıralanır.
- Anahtarlarında dize değeri olan alt öğeler sıradaki sırayla, sözlüksel olarak artan düzende sıralanır.
OrderByValue
OrderByValue()
kullanılırken alt öğeler değerlerine göre sıralanır. Sıralama ölçütleri OrderByChild()
ile aynıdır. Tek fark, belirtilen alt anahtarın değeri yerine düğümün değerinin kullanılmasıdır.