Veri Alma

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

Realtime Database'i kullanabilmeniz için önce şunları yapmanız gerekir:

  • Unity projenizi kaydedin ve Firebase'i kullanacak şekilde yapılandırın.

    • Unity projeniz zaten Firebase'i kullanıyorsa Firebase için kaydedilmiş ve yapılandırılmış demektir.

    • Unity projeniz yoksa örnek bir uygulama indirebilirsiniz.

  • Unity projenize Firebase Unity SDK'yı (özellikle FirebaseDatabase.unitypackage) ekleyin.

Firebase'i Unity projenize eklemenin hem Firebase konsolundaki hem de açık Unity projenizdeki görevleri içerdiğini unutmayın (örneğin, Firebase yapılandırma dosyalarını konsoldan indirir ve ardından bunları Unity projenize taşırsınız).

Veri Alma

Firebase verileri, GetValueAsync() tek seferlik bir çağrıyla veya FirebaseDatabase referansındaki bir etkinliğe eklenerek alınır. Etkinlik işleyici bir kez verilerin ilk durumu için ve veriler her değiştiğinde tekrar çağrılır.

Veritabanı Referansı Alma

Veritabanındaki verileri okumak için DatabaseReference örneği gerekir:

using Firebase;
using Firebase.Database;
using Firebase.Extensions.TaskExtension; // for ContinueWithOnMainThread

public class MyScript: MonoBehaviour {
  void Start() {
    // Get the root reference location of the database.
    DatabaseReference reference = FirebaseDatabase.DefaultInstance.RootReference;
  }
}

Verileri bir kez oku

Belirli bir yoldaki içeriklerin statik anlık görüntüsünü bir kez okumak için GetValueAsync 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.

    FirebaseDatabase.DefaultInstance
      .GetReference("Leaders")
      .GetValueAsync().ContinueWithOnMainThread(task => {
        if (task.IsFaulted) {
          // Handle the error...
        }
        else if (task.IsCompleted) {
          DataSnapshot snapshot = task.Result;
          // Do something with snapshot...
        }
      });

Etkinlikleri dinleyin

Verilerde yapılan değişikliklere abone olmak için etkinlik işleyiciler ekleyebilirsiniz:

Etkinlik Tipik kullanım
ValueChanged Bir yolun tüm içeriğindeki değişiklikleri okuma ve dinleme.
ChildAdded Öğe listelerini alın veya öğe listesine yapılan eklemeleri dinleyin. Listelerde yapılan değişiklikleri izlemek için ChildChanged ve ChildRemoved ile kullanılması önerilir.
ChildChanged Listedeki öğelerde yapılan değişiklikleri bekleyin. Listelerde yapılan değişiklikleri izlemek için ChildAdded ve ChildRemoved ile birlikte kullanın.
ChildRemoved Bir listeden kaldırılan öğeleri bekleyin. Listelerde yapılan değişiklikleri izlemek için ChildAdded ve ChildChanged ile birlikte kullanın.
ChildMoved Sıralı listedeki öğelerin sırasındaki değişiklikleri bekleyin. ChildMoved etkinlikleri her zaman öğenin sırasının değişmesine neden olan ChildChanged etkinliğini takip eder (geçerli sıralama yönteminize göre).

ValueChanged etkinliği

Belirli bir yoldaki içerik değişikliklerine abone olmak için ValueChanged etkinliğini kullanabilirsiniz. Bu etkinlik, işleyici eklendiğinde bir kez ve alt öğeler dahil olmak üzere veriler her değiştiğinde tekrar tetiklenir. Etkinlik geri çağırması, alt veriler de dahil olmak üzere söz konusu 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 örnekte, veritabanından bir skor tablosunun skorlarını alan bir oyun gösterilmektedir:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

ValueChangedEventArgs, etkinlik sırasında veritabanında belirtilen konumda bulunan verileri içeren bir DataSnapshot içerir. Anlık görüntüde Value çağrısı yapıldığında, verileri temsil eden bir Dictionary<string, object> döndürülür. Konumda veri yoksa Value işlevinin çağrılması null sonucunu döndürür.

Bu örnekte, okuma işleminin iptal edilip edilmediğini görmek için args.DatabaseError da incelenmektedir. Örneğin, istemcinin bir Firebase veritabanı konumundan okuma izni yoksa okuma işlemi iptal edilebilir. DatabaseError, hatanın neden oluştuğunu belirtir.

Daha sonra, aynı yola sahip herhangi bir DatabaseReference adresini kullanarak etkinlik aboneliğinizi iptal edebilirsiniz. DatabaseReference örnekleri geçicidir ve herhangi bir yol ile sorguya erişmenin bir yolu olarak düşünülebilir.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders")
        .ValueChanged -= HandleValueChanged; // unsubscribe from ValueChanged.
    }

Alt etkinlikler

Alt etkinlikler, Push() yöntemiyle eklenen yeni bir alt öğe veya UpdateChildrenAsync() 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:

      var ref = FirebaseDatabase.DefaultInstance
      .GetReference("GameSessionComments");

      ref.ChildAdded += HandleChildAdded;
      ref.ChildChanged += HandleChildChanged;
      ref.ChildRemoved += HandleChildRemoved;
      ref.ChildMoved += HandleChildMoved;
    }

    void HandleChildAdded(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildChanged(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildRemoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

    void HandleChildMoved(object sender, ChildChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

ChildAdded etkinliği genellikle Firebase veritabanındaki öğelerin listesini almak için kullanılır. ChildAdded etkinliği, mevcut her alt öğe için bir kez ve belirtilen yola her yeni alt öğe eklendiğinde tekrar tetiklenir. İşleyiciye, yeni alt öğenin verilerini içeren bir anlık görüntü iletilir.

Bir alt düğüm her değiştirildiğinde ChildChanged etkinliği tetiklenir. Buna alt düğümün alt öğelerinde yapılan değişiklikler de dahildir. Genellikle bir öğe listesindeki değişikliklere tepki vermek için ChildAdded ve ChildRemoved etkinlikleriyle birlikte kullanılır. Etkinlik işleyiciye iletilen anlık görüntü, alt öğeye ait güncellenmiş verileri içerir.

Hemen bir alt öğe kaldırıldığında ChildRemoved etkinliği tetiklenir. Genellikle ChildAdded ve ChildChanged geri çağırmalarıyla birlikte kullanılır. Etkinlik geri çağırmasına iletilen anlık görüntü, kaldırılan alt öğenin verilerini içerir.

ChildChanged etkinliği, alt öğenin yeniden sıralanmasına neden olan bir güncelleme tarafından gerçekleştiğinde ChildMoved etkinliği 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.

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score")
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

Bu, valuechanged etkinlik işleyici ile birleştirildiğinde istemciyi veritabanındaki leaderboard ile senkronize eden ve her girişin puanına göre sıralanmış bir sorguyu tanımlar. 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 ChildAdded geri çağırması alırsınız. Firebase veritabanınızda depolanan öğe sayısı 100'den azsa her öğe için ChildAdded geri çağırması etkinleşir.

Öğeler değiştikçe sorguya giren öğeler için ChildAdded geri çağırma, sorgudan çıkan öğeler için ise ChildRemoved 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:

      FirebaseDatabase.DefaultInstance
        .GetReference("Leaders").OrderByChild("score").LimitToLast(1)
        .ValueChanged += HandleValueChanged;
    }

    void HandleValueChanged(object sender, ValueChangedEventArgs args) {
      if (args.DatabaseError != null) {
        Debug.LogError(args.DatabaseError.Message);
        return;
      }
      // Do something with the data in args.Snapshot
    }

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:

  1. Belirtilen alt anahtarda null değerine sahip olan alt öğeler önce gelir.
  2. Belirtilen alt anahtar için false değerine sahip olan alt öğeler ardından gelir. Birden fazla alt öğe false değerine sahipse bunlar anahtara göre sözlüksel olarak sıralanır.
  3. Belirtilen alt anahtar için true değerine sahip olan alt öğeler ardından gelir. Birden fazla alt öğe true değerine sahipse bunlar sözlüksel olarak anahtara göre sıralanır.
  4. 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.
  5. 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.
  6. 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.

  1. 32 bit tam sayı olarak ayrıştırılabilen bir anahtarı olan alt öğeler önce gelir ve artan düzende sıralanır.
  2. 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.