Pobieram dane

Ten dokument zawiera podstawowe informacje o pobieraniu danych oraz o porządkowaniu i filtrowaniu danych Firebase.

Zanim zaczniesz

Zanim zaczniesz korzystać z Realtime Database, musisz:

• Zarejestruj projekt Unity i skonfiguruj go tak, aby używał Firebase.

  • Jeśli Twój projekt Unity korzysta już z Firebase, jest już zarejestrowany i skonfigurowany pod kątem Firebase.

  • Jeśli nie masz projektu Unity, możesz pobrać przykładową aplikację.

• Dodaj do projektu Unity pakiet SDK Firebase Unity (a konkretnie FirebaseDatabase.unitypackage).

Pamiętaj, że dodanie Firebase do projektu Unity wymaga wykonania zadań zarówno w konsoli Firebase, jak i w otwartym projekcie Unity (np. pobierasz pliki konfiguracji Firebase z konsoli, a następnie przenosisz je do projektu Unity).

Pobieram dane

Dane Firebase są pobierane przez jednorazowe wywołanie funkcji GetValueAsync() lub dołączenie do zdarzenia w odwołaniu FirebaseDatabase. Detektor zdarzeń jest wywoływany raz dla stanu początkowego danych i ponownie za każdym razem, gdy dane się zmieniają.

Pobieranie DatabaseReference

Aby odczytać dane z bazy danych, potrzebujesz instancji DatabaseReference:

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;
  }
}

Odczytywanie danych raz

Możesz użyć metody GetValueAsync, aby jednorazowo odczytać statyczną migawkę zawartości w danej ścieżce. Wynik zadania będzie zawierać migawkę ze wszystkimi danymi w tej lokalizacji, w tym danymi podrzędnymi. Jeśli nie ma danych, zwracany jest zrzut null.

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

Nasłuchiwanie zdarzeń

Możesz dodać detektory zdarzeń, aby subskrybować zmiany danych:

Zdarzenie ValueChanged

Możesz użyć zdarzenia ValueChanged, aby zasubskrybować zmiany zawartości w danej ścieżce. To zdarzenie jest wywoływane raz, gdy detektor jest dołączony, i ponownie za każdym razem, gdy dane, w tym elementy podrzędne, ulegną zmianie. Do wywołania zwrotnego zdarzenia przekazywany jest zrzut zawierający wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwracane jest podsumowanie null.

Poniższy przykład pokazuje, jak gra pobiera wyniki z tabeli wyników z bazy danych:

      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 zawiera obiekt DataSnapshot, który zawiera dane w określonej lokalizacji w bazie danych w momencie wystąpienia zdarzenia. Wywołanie metody Value na zrzucie zwraca obiekt Dictionary<string, object> reprezentujący dane. Jeśli w lokalizacji nie ma danych, wywołanie Value zwraca null.

W tym przykładzie sprawdzany jest też obiekt args.DatabaseError, aby zobaczyć, czy odczyt został anulowany. Na przykład odczyt może zostać anulowany, jeśli klient nie ma uprawnień do odczytu z lokalizacji bazy danych Firebase. W polu DatabaseError znajdziesz przyczynę niepowodzenia.

Później możesz zrezygnować z subskrypcji zdarzenia, używając dowolnego elementu DatabaseReference o tej samej ścieżce. Instancje DatabaseReference są tymczasowe i można je traktować jako sposób na uzyskanie dostępu do dowolnej ścieżki i zapytania.

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

Zdarzenia podrzędne

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje, które mają miejsce w przypadku elementów podrzędnych węzła, np. dodanie nowego elementu podrzędnego za pomocą metody Push() lub zaktualizowanie elementu podrzędnego za pomocą metody UpdateChildrenAsync(). Każda z tych metod może być przydatna do nasłuchiwania zmian w konkretnym węźle w bazie danych. Na przykład gra może używać tych metod razem do monitorowania aktywności w komentarzach sesji gry, jak pokazano poniżej:

      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
    }

Zdarzenie ChildAdded jest zwykle używane do pobierania listy elementów z bazy danych Firebase. Zdarzenie ChildAdded jest wywoływane raz dla każdego istniejącego elementu podrzędnego, a następnie za każdym razem, gdy do określonej ścieżki zostanie dodany nowy element podrzędny. Do detektora przekazywany jest zrzut zawierający dane nowego elementu podrzędnego.

Zdarzenie ChildChanged jest wywoływane za każdym razem, gdy węzeł podrzędny zostanie zmodyfikowany. Obejmuje to wszelkie zmiany w elementach podrzędnych węzła podrzędnego. Zwykle jest używany w połączeniu ze zdarzeniami ChildAdded i ChildRemoved, aby reagować na zmiany na liście elementów. Zrzut przekazany do detektora zdarzeń zawiera zaktualizowane dane dotyczące elementu podrzędnego.

Zdarzenie ChildRemoved jest wywoływane, gdy element podrzędny zostanie usunięty. Zwykle jest używana w połączeniu z wywołaniami zwrotnymi ChildAdded i ChildChanged. Zrzut przekazany do wywołania zwrotnego zdarzenia zawiera dane usuniętego elementu podrzędnego.

Zdarzenie ChildMoved jest wywoływane zawsze, gdy zdarzenie ChildChanged jest wywoływane przez aktualizację, która powoduje zmianę kolejności elementu podrzędnego. Jest używana z danymi uporządkowanymi za pomocą OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

Możesz użyć klasy Realtime Database Query, aby pobrać dane posortowane według klucza, wartości lub wartości elementu podrzędnego. Możesz też filtrować posortowane wyniki, aby uzyskać określoną liczbę wyników lub zakres kluczy bądź wartości.

Sortowanie danych

Aby pobrać posortowane dane, zacznij od określenia jednej z metod sortowania, która określi sposób porządkowania wyników:

Możesz używać tylko jednej metody sortowania naraz. Wielokrotne wywołanie metody sortowania w tym samym zapytaniu powoduje błąd.

Poniższy przykład pokazuje, jak możesz zasubskrybować tabelę wyników uporządkowaną według wyniku.

      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
    }

Definiuje to zapytanie, które w połączeniu z detektorem zdarzeń valuechanged synchronizuje klienta z tabelą wyników w bazie danych, uporządkowaną według wyniku każdego wpisu. Więcej informacji o efektywnym porządkowaniu danych znajdziesz w artykule Struktura bazy danych.

Wywołanie metody OrderByChild() określa klucz podrzędny, według którego mają być porządkowane wyniki. W takim przypadku wyniki są sortowane według wartości "score" w każdym elemencie podrzędnym. Więcej informacji o porządkowaniu innych typów danych znajdziesz w artykule Jak są porządkowane dane zapytań.

Filtrowanie danych

Aby filtrować dane, podczas tworzenia zapytania możesz połączyć dowolną metodę limitu lub zakresu z metodą sortowania.

W przeciwieństwie do metod sortowania możesz łączyć wiele funkcji limitu lub zakresu. Możesz na przykład połączyć metody StartAt() i EndAt(), aby ograniczyć wyniki do określonego zakresu wartości.

Nawet jeśli zapytanie ma tylko jedno dopasowanie, podsumowanie nadal jest listą, ale zawiera tylko jeden element.

Ograniczanie liczby wyników

Możesz użyć metod LimitToFirst() i LimitToLast(), aby ustawić maksymalną liczbę elementów podrzędnych do zsynchronizowania w przypadku danego wywołania zwrotnego. Jeśli na przykład użyjesz LimitToFirst(), aby ustawić limit 100, początkowo otrzymasz tylko maksymalnie 100 wywołań zwrotnych ChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, dla każdego z nich zostanie wywołane wywołanie zwrotne ChildAdded.

W miarę zmian elementów otrzymujesz wywołania zwrotne ChildAdded dla elementów, które pojawiają się w zapytaniu, i wywołania zwrotne ChildRemoved dla elementów, które z niego wypadają, dzięki czemu łączna liczba pozostaje na poziomie 100.

Na przykład poniższy kod zwraca najlepszy wynik z tabeli wyników:

      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
    }

Filtruj według klucza lub wartości

Możesz używać funkcji StartAt(), EndAt() i EqualTo(), aby wybierać dowolne punkty początkowe, końcowe i równoważne dla zapytań. Może to być przydatne do dzielenia danych na strony lub znajdowania elementów z elementami podrzędnymi o określonej wartości.

Jak są uporządkowane dane z zapytań

W tej sekcji wyjaśniamy, jak dane są sortowane według poszczególnych metod sortowania w klasie Query.

OrderByChild

Gdy używasz OrderByChild(), dane zawierające określony klucz podrzędny są porządkowane w ten sposób:

1. Dzieci z wartością null dla określonego klucza podrzędnego są wyświetlane jako pierwsze.
2. Następnie wyświetlane są elementy podrzędne z wartością false dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane leksykograficznie według klucza.
3. Następnie wyświetlane są elementy podrzędne z wartością true dla określonego klucza podrzędnego. Jeśli wiele elementów podrzędnych ma wartość true, są one sortowane leksykograficznie według klucza.
4. Następnie wyświetlane są elementy podrzędne z wartością liczbową, posortowane w kolejności rosnącej. Jeśli kilka elementów podrzędnych ma tę samą wartość liczbową dla określonego węzła podrzędnego, są one sortowane według klucza.
5. Ciągi znaków występują po liczbach i są sortowane leksykograficznie w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość dla określonego węzła podrzędnego, są one uporządkowane leksykograficznie według klucza.
6. Obiekty są na końcu i są sortowane leksykograficznie według klucza w kolejności rosnącej.

OrderByKey

Gdy używasz OrderByKey() do sortowania danych, są one zwracane w kolejności rosnącej według klucza.

1. Najpierw wyświetlane są elementy podrzędne z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
2. Następnie wyświetlane są elementy podrzędne z wartością ciągu znaków jako kluczem, posortowane leksykograficznie w porządku rosnącym.

OrderByValue

Gdy używasz OrderByValue(), elementy podrzędne są uporządkowane według wartości. Kryteria porządkowania są takie same jak w przypadku OrderByChild(), z tą różnicą, że używana jest wartość węzła, a nie określonego klucza podrzędnego.