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

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

Başlamadan önce

Uygulamanızı kurduğunuzdan ve Get Started kılavuzunda belirtildiği gibi veritabanına erişebildiğinizden emin olun.

Veriler Alınıyor

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

DatabaseReference alma

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 okuma

Belirli bir yoldaki içeriklerin statik anlık görüntüsünü bir kez okumak için GetValue() yöntemini kullanabilirsiniz. Görev sonucunda, alt veriler de dahil olmak üzere o konumdaki tüm verileri içeren bir anlık görüntü yer alır. 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 yapıldıktan sonra değerin okunabilmesi için Future'ın tamamlanması beklenmelidir. Oyunlar genellikle döngü içinde çalıştığından ve diğer uygulamalara kıyasla daha az geri çağırma odaklı olduğundan, genellikle tamamlanma durumu 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...
    }
  }

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 olmak için dinleyiciler ekleyebilirsiniz:

ValueListener temel sınıf

Geri Arama	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 alma veya öğe listesine eklenenleri dinleme Listelerde yapılan değişiklikleri izlemek için OnChildChanged ve OnChildRemoved ile birlikte kullanılması önerilir.
OnChildChanged	Listedeki öğelerde yapılan değişiklikleri dinleme. Listelerde yapılan değişiklikleri izlemek için OnChildAdded ve OnChildRemoved ile birlikte kullanın.
OnChildRemoved	Listeden kaldırılan öğeleri dinleyin. Listelerde yapılan değişiklikleri izlemek için OnChildAdded ve OnChildChanged ile birlikte kullanın.
OnChildMoved	Sıralı listedeki öğelerin sırasıyla ilgili değişiklikleri dinleyin. OnChildMoved geri aramaları her zaman OnChildChanged öğenin sırasının değişmesi (mevcut sıralama yönteminize göre) nedeniyle yapılan geri aramaları takip eder.

ValueListener sınıfı

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

Önemli: Alt öğelerdeki değişiklikler de dahil olmak üzere, belirtilen veritabanı referansında veriler her değiştirildiğinde OnValueChanged etkinliği çağrılır. Anlık görüntülerinizin boyutunu sınırlamak için yalnızca değişiklikleri izlemek üzere ihtiyaç duyulan en yüksek düzeyde ekleyin. Örneğin, veritabanınızın köküne bir dinleyici eklemeniz önerilmez.

Aşağıdaki örnekte, bir oyunun veritabanından skor tablosu 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ı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 nedenini gösterir.

ChildListener sınıfı

Çocuk etkinlikleri, bir düğümün çocuklarında gerçekleşen belirli işlemlerin sonucunda tetiklenir. Örneğin, PushChild() yöntemiyle yeni bir çocuk eklenmesi veya UpdateChildren() yöntemiyle bir çocuğun güncellenmesi gibi. 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, 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, her mevcut alt öğe için bir kez, belirtilen yola yeni bir alt öğe eklendiğinde ise tekrar çağrılır. Dinleyiciye, yeni çocuğun verilerini içeren bir anlık görüntü iletilir.

OnChildChanged geri çağırma işlevi, bir alt düğüm her değiştirildiğinde çağrılır. Çocuk düğümünün alt öğelerinde yapılan değişiklikler de buna 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.

OnChildRemoved geri çağırma işlevi, doğrudan alt öğe kaldırıldığında 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.

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 tetiklenir. OrderByChild veya OrderByValue ile sıralanmış verilerle kullanılır.

Verileri sıralama ve filtreleme

Anahtara, değere veya alt öğenin değerine göre sıralanmış verileri almak için Realtime Database Query sınıfını kullanabilirsiniz. Sıralanmış sonucu belirli sayıda sonuç veya bir anahtar ya da değer aralığına göre de filtreleyebilirsiniz.

Not: Özellikle istemcide yapılan filtreleme ve sıralama işlemleri maliyetli olabilir. Uygulamanız sorgu kullanıyorsa .indexOn kuralını tanımlayarak bu anahtarları sunucuda dizine ekleyin ve Verilerinizi Dizine Ekleme bölümünde açıklandığı gibi sorgu performansını artırın.

Verileri sıralama

Sıralanmış verileri almak için sonuçların nasıl sıralanacağını belirlemek üzere order-by 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. Aynı sorguda bir order-by yöntemini birden çok kez çağırmak hataya neden olur.

Aşağıdaki örnekte, puana göre sıralanmış bir skor tablosuna 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, firebase::Query tanımlar. ValueListener ile birleştirildiğinde, istemciyi veritabanındaki skor tablosuyla senkronize eder. Skor tablosu, her girişin puanına göre sıralanır. 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öntemine yapılan çağrı, sonuçları sıralamak için kullanılacak 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 verileri nasıl sıralanır? 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ı 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 anahtardan veya değerden büyük ya da bu anahtara veya değere eşit öğeleri döndürür.
EndAt()	Sıralama yöntemine bağlı olarak, belirtilen anahtardan veya değerden küçük ya da ona eşit öğeleri döndürür.
EqualTo()	Sıralama yöntemine bağlı olarak belirtilen anahtara veya değere eşit öğeleri döndürür.

Sıralama yöntemlerinden farklı olarak, birden fazla sınır 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 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ı 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 OnChildAdded geri araması alırsınız. Firebase veritabanınızda 100'den az öğe depolanıyorsa her öğe için bir OnChildAdded geri çağırma işlemi tetiklenir.

Öğeler değiştikçe sorguya giren öğeler için OnChildAdded, sorgudan çıkan öğeler için OnChildRemoved geri çağırma alırsınız. Böylece toplam sayı 100 olarak 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.

Anahtara veya değere göre filtreleme

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

Sorgu verilerinin sıralanma ş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ılırken belirtilen alt anahtarı içeren veriler aşağıdaki gibi sıralanır:

1. Belirtilen çocuk anahtarı için null değeri olan çocuklar önceliklidir.
2. Belirtilen alt anahtar için false değerine sahip çocuklar bir sonraki sırada yer alır. Birden fazla alt öğenin değeri false ise bunlar anahtara göre sözlük sırasına göre sıralanır.
3. Belirtilen alt anahtar için true değerine sahip çocuklar bir sonraki sırada yer alır. Birden fazla alt öğenin değeri true ise bunlar anahtara göre sözlük sırasına göre sıralanır.
4. Sayısal değere sahip çocuklar, artan düzende sıralanarak gösterilir. Belirtilen alt düğüm için birden fazla alt öğe aynı sayısal değere sahipse bunlar anahtara göre sıralanır.
5. 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 anahtara göre sözlük sırasına göre sıralanır.
6. Nesneler en sona gelir ve anahtara göre artan sözlük sırasıyla sıralanır.

OrderByKey

Verilerinizi sıralamak için OrderByKey() işlevini kullandığınızda veriler, anahtara göre artan sırada döndürülür.

1. 32 bitlik bir tam sayı olarak ayrıştırılabilen anahtara sahip çocuklar, artan düzende sıralanarak ilk sırada yer alır.
2. Anahtarı dize değeri olan çocuklar, sözlük sıralamasına göre artan düzende sıralanır.

OrderByValue

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

Sonraki adımlar

• Veri tasarrufu