Pobieram dane

W tym dokumencie znajdziesz podstawowe informacje o pobieraniu danych oraz ich sortowaniu i filtrowaniu.

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 w Unity korzysta już z Firebase, jest już zarejestrowany i skonfigurowany pod kątem tej usługi.

    • Jeśli nie masz projektu Unity, możesz pobrać próbną aplikację.

  • Dodaj pakiet SDK Firebase Unity (szczególnie plik FirebaseDatabase.unitypackage) do projektu Unity.

Pamiętaj, że dodanie Firebase do projektu Unity wymaga wykonania zadań zarówno w konsoli Firebase, jak i w otwartym projekcie Unity (np. pobieranie plików konfiguracji Firebase z konsoli i przenoszenie ich do projektu Unity).

Pobieranie danych

Dane Firebase są pobierane przez jednorazowe wywołanie metody GetValueAsync() lub przez dołączenie do zdarzenia za pomocą odwołania FirebaseDatabase. Listener jest wywoływany raz w przypadku początkowego stanu danych i ponownie za każdym razem, gdy dane ulegną zmianie.

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

jednokrotny odczyt danych,

Aby odczytać statyczny zrzut treści w danym miejscu, możesz użyć metody GetValueAsync. Wynik zadania będzie zawierać migawkę ze wszystkimi danymi w tej lokalizacji, w tym danymi podrzędnymi. Jeśli nie ma żadnych danych, zwrócony zostanie podany null.

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

Nasłuchiwanie zdarzeń

Możesz dodać odbiorników zdarzeń, aby subskrybować zmiany danych:

Zdarzenie Typowe zastosowanie
ValueChanged czytać i słuchać zmian w całej zawartości ścieżki;
ChildAdded pobierać listy elementów lub słuchać dodanych elementów na liście; Sugerowane użycie z elementami ChildChanged i ChildRemoved do monitorowania zmian w listach.
ChildChanged Słuchaj zmian elementów na liście. Używaj elementów ChildAdded i ChildRemoved, aby monitorować zmiany w listach.
ChildRemoved Słuchaj, czy elementy są usuwane z listy. Używaj elementów ChildAdded i ChildChanged, aby monitorować zmiany w listach.
ChildMoved Słuchaj zmian kolejności elementów na liście uporządkowanej. Zdarzenia ChildMoved zawsze podążają za zdarzeniem ChildChanged, które spowodowało zmianę kolejności elementów (na podstawie bieżącej metody sortowania).

Zdarzenie ValueChanged

Zdarzenia ValueChanged możesz używać do subskrybowania zmian treści na danej ścieżce. To zdarzenie jest wywoływane raz, gdy słuchacz jest podłączony, oraz za każdym razem, gdy dane, w tym elementy podrzędne, ulegną zmianie. Do funkcji wywołania zwrotnego zdarzenia przekazywany jest zrzut zawierający wszystkie dane w danej lokalizacji, w tym dane podrzędne. Jeśli nie ma żadnych danych, zwracany jest obraz null.

Ten przykład pokazuje grę, która pobiera z bazy danych wyniki z tablicy liderów:

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

W tym przykładzie sprawdzana jest również wartość args.DatabaseError, aby sprawdzić, 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. DatabaseError wskazuje, dlaczego wystąpił błąd.

Później możesz anulować subskrypcję wydarzenia za pomocą dowolnego elementu DatabaseReference, który ma tę samą ścieżkę. DatabaseReference instancje są efemeryczne 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.
    }

Skopiowane wydarzenia

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje wykonywane na podrzędnych węzłach, np. dodanie nowego podrzędnego za pomocą metody Push() lub zaktualizowanie podrzędnego za pomocą metody UpdateChildrenAsync(). Każdy z nich może być przydatny do monitorowania zmian w konkretnym węźle w bazie danych. Na przykład gra może używać tych metod razem, aby monitorować aktywność 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 potem za każdym razem, gdy do określonej ścieżki zostanie dodany nowy element podrzędny. Listenerowi przekazywany jest migawkowy widok zawierający dane nowego elementu podrzędnego.

Zdarzenie ChildChanged jest wywoływane za każdym razem, gdy modyfikowany jest węzeł podrzędny. Obejmuje to wszelkie modyfikacje potomków węzła podrzędnego. Jest ono zazwyczaj używane w połączeniu ze zdarzeniami ChildAdded i ChildRemoved, aby reagować na zmiany w liście elementów. Zrzut przekazany do odbiornika zdarzeń zawiera zaktualizowane dane dotyczące podrzędnego obiektu.

Wydarzenie ChildRemoved jest wywoływane, gdy usuwasz element nadrzędny. Jest ona zwykle używana w połączeniu z funkcjami wywołania ChildAdded i ChildChanged. Zrzut podany do wywołania zdarzenia zawiera dane usuniętego podrzędnego.

Zdarzenie ChildMoved jest wywoływane za każdym razem, gdy zdarzenie ChildChanged jest wywoływane przez aktualizację, która powoduje zmianę kolejności elementów w podrzędnym. Jest on używany z danymi uporządkowanymi za pomocą funkcji OrderByChild lub OrderByValue.

Sortowanie i filtrowanie danych

Aby pobrać dane posortowane według klucza, wartości lub wartości podrzędnego, możesz użyć klasy Realtime Database Query. Możesz też ograniczyć liczbę wyników do określonej liczby lub do określonego zakresu kluczy bądź wartości.

Sortowanie danych

Aby pobrać posortowane dane, najpierw określ jedną z metod sortowania, która określi sposób sortowania wyników:

Metoda Wykorzystanie
OrderByChild() Porządkuj wyniki według wartości określonego klucza podrzędnego.
OrderByKey() Uporządkuj wyniki według kluczy podrzędnych.
OrderByValue() Porządkuj wyniki według wartości elementów podrzędnych.

Możesz użyć tylko jednej metody sortowania naraz. Wywołanie metody sortowania kilka razy w tym samym zapytaniu powoduje błąd.

Ten przykład pokazuje, jak można subskrybować tablicę wyników z podziałem na punkty.

      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
    }

Określa ono zapytanie, które w połączeniu z obsługą zdarzenia valuechanged synchronizuje klienta z listą liderów w bazie danych, posortowaną według wyniku każdego wpisu. Więcej informacji o skutecznym porządkowaniu danych znajdziesz w artykule Uporządkuj bazę danych.

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

Filtrowanie danych

Aby filtrować dane, podczas tworzenia zapytania możesz połączyć dowolną metodę limit lub range z metodą order-by.

Metoda Wykorzystanie
LimitToFirst() Określa maksymalną liczbę elementów do zwrócenia z początku uporządkowanej listy wyników.
LimitToLast() Określa maksymalną liczbę elementów do zwrócenia z końca posortowanej listy wyników.
StartAt() Zwraca elementy, których wartość jest większa lub równa określonemu kluczowi lub wartości, w zależności od wybranej metody sortowania.
EndAt() Zwraca elementy, które są mniejsze lub równe określonemu kluczowi lub wartości, w zależności od wybranej metody sortowania.
EqualTo() Zwraca elementy o wartości określonej w kluczu lub wartości w zależności od wybranej metody sortowania.

W przeciwieństwie do metod porządkowania według kolumny możesz łączyć wiele funkcji limit i zakres. Możesz np. połączyć metody StartAt() i EndAt(), aby ograniczyć wyniki do określonego zakresu wartości.

Nawet wtedy, gdy zapytanie ma tylko 1 pasujący element, snapshot jest nadal listą, ale zawiera tylko 1 element.

Ograniczanie liczby wyników

Aby ustawić maksymalną liczbę elementów podrzędnych, które mają być synchronizowane w przypadku danego wywołania zwrotnego, możesz użyć metod LimitToFirst() i LimitToLast(). Jeśli np. użyjesz parametru LimitToFirst(), aby ustawić limit na 100, początkowo otrzymasz tylko do 100 wywołań funkcji ChildAdded. Jeśli w bazie danych Firebase masz mniej niż 100 elementów, dla każdego z nich zostanie wywołana funkcja ChildAdded.

Gdy elementy się zmieniają, otrzymujesz ChildAdded wywołania zwrotne dla elementów, które wchodzą do zapytania, oraz ChildRemoved wywołania zwrotne dla elementów, które z niego wypadają, dzięki czemu łączna liczba pozostaje równa 100.

Na przykład poniższy kod zwraca najwyższy wynik z tablicy lideró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
    }

Filtrowanie według klucza lub wartości

Za pomocą funkcji StartAt(), EndAt() i EqualTo() możesz wybrać dowolne punkty początkowe, końcowe i równoważne w zapytaniach. Może to być przydatne do przewijania danych lub znajdowania elementów podrzędnych o określonej wartości.

Sposób sortowania danych zapytania

W tej sekcji wyjaśniamy, jak dane są sortowane według każdej z metod sortowania w klasie Query.

OrderByChild

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

  1. Najpierw są wyświetlane elementy podrzędne, dla których wartość atrybutu podrzędnego null jest równa null.
  2. Następnie podawane są elementy podrzędne, dla których wartość określonego klucza podrzędnego to false. Jeśli wiele elementów podrzędnych ma wartość false, są one sortowane alfabetycznie według klucza.
  3. Następnie podawane są elementy podrzędne, dla których wartość określonego klucza podrzędnego to true. Jeśli wiele elementów podrzędnych ma wartość true, są one sortowane alfabetycznie według klucza.
  4. Następnie pojawiają się elementy z wartością liczbową, posortowane w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość numeryczną w przypadku określonego węzła podrzędnego, są one sortowane według klucza.
  5. Ciągi tekstowe występują po liczbach i są sortowane alfabetycznie w kolejności rosnącej. Jeśli wiele elementów podrzędnych ma tę samą wartość w wybranym węźle podrzędnym, są one uporządkowane alfabetycznie według klucza.
  6. Obiekty znajdują się na końcu i są posortowane leksykograficznie według klucza w kolejności rosnącej.

OrderByKey

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

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

OrderByValue

W przypadku użycia OrderByValue() elementy podrzędne są sortowane według wartości. Kryteria sortowania są takie same jak w przypadku atrybutu OrderByChild(), z tym że zamiast wartości określonego klucza podrzędnego jest używana wartość węzła.