Bu belge, veri almanın temellerini ve Firebase verilerinin nasıl sıralanıp filtreleneceğini kapsar.
Sen başlamadan önce
Uygulamanızı kurduğunuzdan ve Get Started kılavuzunda anlatıldığı gibi veritabanına erişebildiğinizden emin olun.
Veri Alma
Firebase verileri GetValue() ya tek seferlik çağrı yapılarak veya FirebaseDatabase referansındaki ValueListener bağlanarak alınır. Değer dinleyicisi, verinin başlangıç durumu için bir kez ve veri değiştiğinde tekrar çağrılır.
Veritabanı Referansı Alın
Veritabanına veri yazmak için DatabaseReference örneğine ihtiyacınız vardır:
// Get the root reference location of the database.
firebase::database::DatabaseReference dbref = database->GetReference();
Verileri bir kez okuyun
Belirli bir yoldaki içeriğin 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 o konumdaki tüm verileri içeren bir anlık görüntü içerecektir. Veri yoksa döndürülen anlık görüntü null olur.
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").GetValue();
Bu noktada istek yapıldı ancak değeri okuyabilmemiz için Geleceğin tamamlanmasını beklememiz gerekiyor. Oyunlar genellikle bir döngüde çalıştığından ve diğer uygulamalara göre daha az geri çağrıldığından, genellikle tamamlanmak üzere 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...
}
}
Bu, bazı temel hata kontrolünü gösterir; hata kontrolü hakkında daha fazla bilgi ve sonucun ne zaman hazır olduğunu belirlemenin yolları için firebase::Future referansına bakın.
Etkinlikleri dinle
Verilerdeki değişikliklere abone olmak için dinleyiciler ekleyebilirsiniz:
ValueListener temel sınıfı
| Geri çağırmak | Tipik kullanım |
|---|---|
OnValueChanged | Bir yolun tüm içeriğindeki değişiklikleri okuyun ve dinleyin. |
OnChildListener temel sınıfı
OnChildAdded | Öğe listelerini alın veya öğe listesine yapılan eklemeleri dinleyin. Listelerdeki değişiklikleri izlemek için OnChildChanged ve OnChildRemoved ile önerilen kullanım. |
OnChildChanged | Listedeki öğelerde yapılan değişiklikleri dinleyin. Listelerdeki değişiklikleri izlemek için OnChildAdded ve OnChildRemoved ile birlikte kullanın. |
OnChildRemoved | Listeden kaldırılan öğeleri dinleyin. Listelerdeki değişiklikleri izlemek için OnChildAdded ve OnChildChanged ile birlikte kullanın. |
OnChildMoved | Sıralı bir listedeki öğelerin sırasındaki değişiklikleri dinleyin. OnChildMoved geri aramaları, öğenin sırasının değişmesi nedeniyle (geçerli sıralama yönteminize göre) her zaman OnChildChanged geri aramalarını takip eder. |
ValueListener sınıfı
Belirli bir yoldaki içeriklerde yapılan değişikliklere abone olmak için OnValueChanged geri aramalarını kullanabilirsiniz. Bu geri arama, dinleyici eklendiğinde bir kez tetiklenir ve çocuklar da dahil olmak üzere veriler her değiştiğinde yeniden tetiklenir. Geri aramaya, alt veriler de dahil olmak üzere o konumdaki tüm verileri içeren bir anlık görüntü iletilir. Veri yoksa döndürülen anlık görüntü null olur.
Aşağıdaki örnek, veritabanından skor tablosunun puanlarını alan bir oyunu göstermektedir:
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<DataSnaphot> sonucu, olay anında veritabanında belirtilen konumdaki verileri içerir. Anlık görüntüde value() öğesinin çağrılması, verileri temsil eden bir Variant döndürür.
Bu örnekte, okumanın iptal edilip edilmediğini görmek için OnCancelled yöntemi de geçersiz kılınır. Örneğin, istemcinin Firebase veritabanı konumundan okuma izni yoksa okuma iptal edilebilir. database::Error hatanın neden oluştuğunu gösterecektir.
ChildListener sınıfı
Alt olaylar, PushChild() yöntemi aracılığıyla eklenen yeni bir alt öğe veya UpdateChildren() yöntemi aracılığıyla güncellenen bir alt öğe gibi bir işlemden bir düğümün alt öğelerinin başına gelen belirli işlemlere yanıt olarak tetiklenir. Bunların her biri bir veritabanındaki belirli bir düğümde yapılan değişiklikleri dinlemek için yararlı 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 araması genellikle Firebase veritabanındaki öğelerin listesini almak için kullanılır. OnChildAdded geri çağrısı, mevcut her alt öğe için bir kez ve ardından belirtilen yola her yeni alt öğe eklendiğinde yeniden çağrılır. Dinleyiciye yeni çocuğun verilerini içeren bir anlık görüntü iletilir.
OnChildChanged geri çağrısı, bir alt düğüm değiştirildiğinde her zaman ç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. Dinleyiciye iletilen anlık görüntü, alt öğeye ilişkin güncellenmiş verileri içerir.
OnChildRemoved geri çağrısı, hemen bir alt öğe kaldırıldığında tetiklenir. Genellikle OnChildAdded ve OnChildChanged geri çağrılarıyla birlikte kullanılır. Geri aramaya iletilen anlık görüntü, kaldırılan alt öğenin verilerini içerir.
OnChildMoved geri çağrısı, OnChildChanged çağrısı alt öğenin yeniden sıralanmasına neden olan bir güncelleştirme tarafından başlatıldığında tetiklenir. OrderByChild veya OrderByValue ile sıralanan verilerle kullanılır.
Verileri sıralama ve filtreleme
Anahtara, değere veya bir alt öğenin değerine göre sıralanmış verileri almak için Gerçek Zamanlı Veritabanı Query sınıfını kullanabilirsiniz. Ayrıca sıralanan sonucu belirli sayıda sonuca veya bir anahtar veya değer aralığına göre filtreleyebilirsiniz.
Verileri sırala
Sıralanmış verileri almak için, sonuçların nasıl sıralanacağını belirlemek üzere sıralama yöntemlerinden birini belirterek başlayın:
| Yöntem | Kullanım |
|---|---|
OrderByChild() | Sonuçları belirtilen 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 tek bir sipariş yöntemi kullanabilirsiniz. Aynı sorguda bir sıralama yöntemini birden çok kez çağırmak hataya neden olur.
Aşağıdaki örnek, puana göre sıralanmış bir puan sıralama 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, her girişin puanına göre sıralanan veritabanındaki sıralama tablosuyla senkronize eden bir firebase::Query tanımlar. Verilerinizi verimli bir şekilde yapılandırma hakkında daha fazla bilgiyi Veritabanınızı Yapılandırma bölümünde okuyabilirsiniz.
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 bkz . Sorgu verileri nasıl sıralanır ?
Verileri filtreleme
Verileri filtrelemek için, sorgu oluştururken limit veya aralık yöntemlerinden herhangi birini sıralama yöntemiyle birleştirebilirsiniz.
| Yöntem | Kullanım |
|---|---|
LimitToFirst() | Sıralı sonuç listesinin başı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 anahtara veya değere eşit veya ondan büyük öğeleri döndürün. |
EndAt() | Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtara veya değere eşit veya ondan küçük öğeleri döndürün. |
EqualTo() | Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtara veya değere eşit öğeleri döndürün. |
Sıralama yöntemlerinden farklı olarak birden fazla limit veya aralık fonksiyonunu 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 yalnızca tek bir eşleşme olsa bile anlık görüntü hâlâ bir listedir; yalnızca tek bir öğe içerir.
Sonuç sayısını sınırlayın
Belirli bir geri çağırma için senkronize edilecek maksimum alt çocuk sayısını ayarlamak için LimitToFirst() ve LimitToLast() yöntemlerini kullanabilirsiniz. Örneğin, LimitToFirst() yöntemini 100'lük bir sınır ayarlamak için kullanırsanız, başlangıçta yalnızca 100'e kadar OnChildAdded geri arama alırsınız. Firebase veritabanınızda depolanan öğe sayısı 100'den azsa her öğe için bir OnChildAdded geri çağrısı tetiklenir.
Öğeler değiştikçe, sorguya giren öğeler için OnChildAdded geri aramaları ve sorgudan çıkan öğeler için OnChildRemoved geri aramaları alırsınız; böylece toplam sayı 100'de kalır.
Örneğin, aşağıdaki kod bir skor tablosundaki en yüksek puanı 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 filtrele
Sorgular için rastgele başlangıç, bitiş ve eşdeğerlik noktaları seçmek amacıyla StartAt() , EndAt() ve EqualTo() kullanabilirsiniz. Bu, verileri sayfalara ayırmak veya belirli bir değere sahip alt öğelerin bulunduğu öğeleri bulmak için yararlı olabilir.
Sorgu verileri nasıl sıralanır?
Bu bölümde verilerin Query sınıfındaki sıralama yöntemlerinin her birine göre nasıl sıralandığı açıklanmaktadır.
OrderByChild
OrderByChild() kullanıldığında, belirtilen alt anahtarı içeren veriler şu şekilde sıralanır:
- Belirtilen alt anahtar için
nulldeğeri olan çocuklar önce gelir. - Daha sonra belirtilen alt anahtar için
falsedeğerine sahip çocuklar gelir. Birden fazla çocuğunfalsedeğeri varsa, bunlar sözlüksel olarak anahtara göre sıralanır. - Daha sonra belirtilen alt anahtar için
truedeğeri olan çocuklar gelir. Birden fazla çocuğuntruedeğeri varsa, bunlar sözlüksel olarak anahtara göre sıralanır. - Daha sonra sayısal değeri olan çocuklar artan düzende sıralanarak gelir. Birden fazla alt öğe, belirtilen alt düğüm için aynı sayısal değere sahipse anahtara göre sıralanır.
- Dizeler sayılardan sonra gelir ve sözlükbilimsel olarak artan düzende sıralanır. Belirtilen alt düğüm için birden fazla alt öğe aynı değere sahipse, bunlar sözlüksel olarak anahtara göre sıralanır.
- Nesneler en sonda gelir ve sözlükbilimsel olarak anahtara göre artan düzende sıralanır.
OrderByKey
Verilerinizi sıralamak için OrderByKey() kullanıldığında, veriler anahtara göre artan sırada döndürülür.
- 32 bitlik bir tamsayı olarak ayrıştırılabilen bir anahtarı olan çocuklar, artan düzende sıralanarak önce gelir.
- Anahtarları dize değeri olan çocuklar daha sonra sözlükbilimsel olarak artan düzende sıralanır.
OrderByValue
OrderByValue() kullanıldığında, çocuklar değerlerine göre sıralanır. Sıralama kriterleri, belirtilen alt anahtarın değeri yerine düğümün değerinin kullanılması dışında OrderByChild() ile aynıdır.