C++ için Firebase Realtime Database ile Veri Alma

Bu belgede, veri alma ve Firebase verilerini sıralama ve filtrelemeyle ilgili temel bilgiler verilmektedir.

Başlamadan önce

Uygulamanızı ayarladığınızdan ve Get Started kılavuzunda açıklandığı şekilde veritabanına erişebildiğinizden emin olun.

Veriler Alınıyor

Firebase verileri, GetValue()'e tek seferlik bir çağrı yaparak veya FirebaseDatabase referansında bir ValueListener'e bağlanarak alınır. Değer dinleyicisi, verilerin ilk durumu için bir kez ve veriler her değiştiğinde tekrar çağrılır.

DatabaseReference alma

Veritabanına veri yazmak için bir 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 okuma

Belirli bir yoldaki içeriklerin statik anlık görüntüsünü tek seferde okumak için GetValue() yöntemini kullanabilirsiniz. Görev sonucu, alt veriler dahil olmak üzere bu 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").GetValue();

İstek gönderilmiş olsa da değeri okuyabilmek için Future işlevinin tamamlanmasını beklememiz gerekir. Oyunlar genellikle döngü halinde çalıştığı ve diğer uygulamalara kıyasla geri çağırma işlevi daha az olduğu için genellikle tamamlanma için anket 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 örnekte bazı temel hata kontrolleri gösterilmektedir. Hata kontrolü ve sonucun ne zaman hazır olduğunu belirleme yöntemleri hakkında daha fazla bilgi için firebase::Future referansına bakın.

Etkinlikleri dinleme

Verilerdeki değişikliklere abone olacak dinleyiciler ekleyebilirsiniz:

ValueListener temel sınıf

Geri Arama	Tipik kullanım
OnValueChanged	Bir yolun tüm içeriklerindeki değişiklikleri okuyup dinleyebilirsiniz.

OnChildListener temel sınıf

OnChildAdded	Öğe listelerini alın veya öğe listesine eklenen öğeleri dinleyin. Listelerdeki değişiklikleri izlemek için OnChildChanged ve OnChildRemoved ile birlikte kullanılması önerilir.
OnChildChanged	Listedeki öğelerde yapılan değişiklikleri dinleme Listelerdeki değişiklikleri izlemek için OnChildAdded ve OnChildRemoved ile birlikte kullanın.
OnChildRemoved	Bir listeden öğelerin kaldırılmasını dinleyin. Listelerdeki değişiklikleri izlemek için OnChildAdded ve OnChildChanged ile birlikte kullanın.
OnChildMoved	Sıralı bir listedeki öğelerin sırasıyla ilgili değişiklikleri dinleyin. Öğenin sırasının değişmesi (geçerli sıralama yönteminize göre) nedeniyle OnChildMoved geri çağırma işlevleri her zaman OnChildChanged geri çağırma işlevlerini takip eder.

ValueListener sınıfı

Belirli bir yoldaki içeriklerde yapılan değişikliklere abone olmak için OnValueChanged geri çağırma işlevlerini kullanabilirsiniz. Bu geri çağırma, dinleyici eklendiğinde bir kez ve çocuklar dahil veriler her değiştiğinde tekrar tetiklenir. Geri çağırma işlevine, alt veriler dahil olmak üzere bu 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.

Önemli: OnValueChanged etkinliği, çocuklarda yapılan değişiklikler de dahil olmak üzere belirtilen veritabanı referansında her veri değişikliğinde çağrılır. Anlık görüntülerinizin boyutunu sınırlamak için yalnızca değişiklikleri izlemek için gereken en yüksek düzeyde ekleyin. Örneğin, veritabanınızın köküne bir dinleyici eklemek önerilmez.

Aşağıdaki örnekte, bir oyunun veritabanından liderlik tablosunun puanlarını nasıl aldığı 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("Leaders").AddValueListener(listener);

Future&ltDataSnapshot&gt sonucu, etkinlik sırasında veritabanında belirtilen konumdaki verileri içerir. Bir 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 Firebase veritabanı konumundan okuma izni yoksa okuma işlemi iptal edilebilir. database::Error, hatanın nedenini belirtir.

ChildListener sınıfı

Alt öğe etkinlikleri, bir işlemden kaynaklanan belirli işlemlere (ör. PushChild() yöntemi aracılığıyla eklenen yeni bir alt öğe veya UpdateChildren() yöntemi aracılığıyla güncellenen bir alt öğe) yanıt olarak tetiklenir. Bunların her biri birlikte, veritabanındaki belirli bir düğümdeki değişiklikleri dinlemek için yararlı olabilir. Örneğin, bir oyun, aşağıdaki 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&ltfirebase::database::DataSnapshot&gt result =
    dbRef.GetReference("GameSessionComments").AddChildListener(listener);

OnChildAdded geri çağırma işlevi genellikle bir Firebase veritabanındaki öğelerin listesini almak için kullanılır. OnChildAdded geri çağırma işlevi, mevcut her alt öğe için bir kez ve daha sonra belirtilen yola her yeni alt öğe eklendiğinde tekrar çağrılır. Dinleyiciye yeni alt öğenin verilerini içeren bir anlık görüntü iletilir.

OnChildChanged geri çağırma işlevi, bir alt öğe değiştirildiğinde her zaman çağrılır. Buna, alt öğelerin alt öğelerinde yapılan tüm 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 öğeyle ilgili güncellenmiş verileri içerir.

Doğrudan çocuk kaldırıldığında OnChildRemoved geri çağırma işlevi tetiklenir. Genellikle OnChildAdded ve OnChildChanged geri çağırmalarıyla birlikte kullanılır. Geri çağırma işlevine iletilen anlık görüntü, kaldırılan alt öğenin verilerini içerir.

OnChildMoved geri çağırma işlevi, OnChildChanged çağrısı alt öğenin yeniden sıralanmasına neden olan bir güncelleme tarafından her tetiklendiğinde etkinleştirilir. 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 Realtime Database Query sınıfını kullanabilirsiniz. Sıralı sonucu belirli bir sonuç sayısına veya anahtar ya da değer aralığına göre de filtreleyebilirsiniz.

Not: Filtreleme ve sıralama, özellikle istemcide yapıldığında pahalı olabilir. Uygulamanız sorgu kullanıyorsa bu anahtarları sunucuda dizine eklemek ve sorgu performansını iyileştirmek için .indexOn kuralını tanımlayın. Verilerinizi dizine ekleme bölümünde açıklandığı gibi yapın.

Verileri sıralama

Sıralı verileri almak için sonuçların nasıl sıralandığını belirlemek üzere sıralama yöntemlerinden birini belirterek başlayın:

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 öğe değerlerine göre sıralayın.

Aynı anda yalnızca bir sıralama yöntemi kullanabilirsiniz. Sıralama yönteminin aynı sorgu içinde birden çok kez çağrılması hata verir.

Aşağıdaki örnekte, puana göre sıralanan bir puan liderliğine nasıl abone olabileceğiniz gösterilmektedir.

  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 müşteriyi veritabanındaki lider tabloyla senkronize eden (her girişin puanına göre sıralanır) bir firebase::Query tanımlar. Verilerinizi verimli bir şekilde yapılandırma hakkında daha fazla bilgiyi Veritabanınızı Yapılandırma başlıklı makalede bulabilirsiniz.

OrderByChild() yönteminin çağrısı, sonuçların sıralanacağı alt anahtarı belirtir. Bu durumda sonuçlar, her 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 verilerinin sıralaması başlıklı makaleyi inceleyin.

Veri filtreleme

Verileri filtrelemek için sorgu oluştururken sınır veya aralık yöntemlerinden herhangi birini bir sıralama yöntemiyle birleştirebilirsiniz.

Yöntem	Kullanım
LimitToFirst()	Sıralı sonuç listesinin başından döndürülecek maksimum öğe sayısını belirler.
LimitToLast()	Sıralı sonuç listesinin sonundan döndürülecek maksimum öğe sayısını belirler.
StartAt()	Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtar veya değerden büyük ya da bu değere eşit öğeleri döndürme
EndAt()	Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtar veya değerden düşük ya da ona eşit öğeleri döndürme
EqualTo()	Seçilen sıralama yöntemine bağlı olarak, belirtilen anahtara veya değere eşit öğeleri döndürme

Sıralama yöntemlerinin aksine, birden fazla sınır veya aralık işlevini birleştirebilirsiniz. Örneğin, sonuçları belirli bir değer aralığına 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ü bir liste olmaya devam eder. Yalnızca tek bir öğe içerir.

Sonuç sayısını sınırlama

Belirli bir geri çağırma için senkronize edilecek maksimum çocuk sayısını ayarlamak üzere LimitToFirst() ve LimitToLast() yöntemlerini kullanabilirsiniz. Örneğin, 100 sınırı belirlemek için LimitToFirst() kullanırsanız başlangıçta yalnızca 100'e kadar OnChildAdded geri çağırma alırsınız. Firebase veritabanınızda 100'den az öğe depolanıyorsa her öğe için bir OnChildAdded geri çağırma işlevi tetiklenir.

Öğeler değiştikçe, toplam sayının 100'de kalması için sorguya giren öğeler için OnChildAdded geri çağırma ve sorgudan çıkan öğeler için OnChildRemoved geri çağırma alırsınız.

Örneğin, aşağıdaki kod bir liderlik 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.

Anahtara veya değere göre filtreleme

Sorgular için rastgele başlangıç, bitiş ve eşdeğerlik noktaları seçmek üzere StartAt(), EndAt() ve EqualTo() değerlerini kullanabilirsiniz. Bu, verileri sayfalara ayırmak veya belirli bir değere sahip alt öğeleri olan öğeleri bulmak için yararlı olabilir.

Sorgu verilerinin sıralama şekli

Bu bölümde, verilerin Query sınıfındaki her bir sıralama yöntemine göre nasıl sıralandığı açıklanmaktadır.

OrderByChild

OrderByChild() kullanıldığında, belirtilen alt anahtarı içeren veriler aşağıdaki gibi sıralanır:

1. Belirtilen alt anahtar için null değerine sahip alt öğeler önce gelir.
2. Ardından, belirtilen alt anahtar için false değerine sahip alt öğeler gelir. Birden fazla çocuğun değeri false ise anahtara göre alfabetik olarak sıralanır.
3. Ardından, belirtilen alt anahtar için true değerine sahip alt öğeler gelir. Birden fazla alt öğenin değeri true ise bu öğeler anahtara göre alfabetik olarak sıralanır.
4. Ardından, sayısal değere sahip alt öğeler artan düzende sıralanır. Belirtilen alt öğe düğümü için birden fazla alt öğenin sayısal değeri aynıysa bu alt öğeler anahtara göre sıralanır.
5. Dizelerin sıralaması, sayılardan sonra alfabetik olarak artan düzende yapılır. Belirtilen alt öğe düğümü için birden fazla alt öğe aynı değere sahipse bu öğeler anahtara göre alfabetik olarak sıralanır.
6. Nesneler en son gelir ve anahtara göre artan düzende alfabetik olarak sıralanır.

OrderByKey

Verilerinizi sıralamak için OrderByKey() kullanıldığında veriler, anahtara göre artan düzende döndürülür.

1. 32 bitlik tam sayı olarak ayrıştırılabilen bir anahtara sahip alt öğeler önce gelir ve artan düzende sıralanır.
2. Anahtarı dize değeri olan alt öğeler, artan sözlük sırasına göre sıralanır.

OrderByValue

OrderByValue() kullanıldığında alt öğeler değerlerine göre sıralanır. Sıralama ölçütleri, belirtilen alt anahtarın değeri yerine düğümün değeri kullanıldığı dışında OrderByChild() ile aynıdır.

Sonraki adımlar

• Veri Kaydetme