Pobieranie danych

W tym dokumencie opisano podstawy pobierania danych oraz porządkowania i filtrowania danych Firebase.

Zanim zaczniesz

Zanim będziesz mógł korzystać z Bazy danych czasu rzeczywistego , musisz:

  • Zarejestruj swój projekt Unity i skonfiguruj go do korzystania z Firebase.

    • Jeśli Twój projekt Unity korzysta już z Firebase, oznacza to, że jest już zarejestrowany i skonfigurowany dla Firebase.

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

  • Dodaj pakiet SDK Firebase Unity (w szczególności FirebaseDatabase.unitypackage ) do swojego projektu Unity.

Pamiętaj, że dodanie Firebase do projektu Unity obejmuje zadania zarówno w konsoli Firebase , jak i w otwartym projekcie Unity (na przykład pobierasz pliki konfiguracyjne Firebase z konsoli, a następnie przenosisz je do projektu Unity).

Pobieranie danych

Dane Firebase są pobierane przez jednorazowe wywołanie GetValueAsync() lub dołączenie do zdarzenia w odniesieniu do FirebaseDatabase . Nasłuchiwanie zdarzeń jest wywoływane raz dla stanu początkowego danych i ponownie przy każdej zmianie danych.

Uzyskaj odniesienie do bazy danych

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

Przeczytaj dane raz

Możesz użyć metody GetValueAsync , aby jednorazowo odczytać statyczną migawkę zawartości w danej ścieżce. Wynik zadania będzie zawierał migawkę zawierającą wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócona migawka ma 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...
        }
      });

Słuchaj wydarzeń

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

Wydarzenie Typowe użycie
ValueChanged Czytaj i słuchaj zmian w całej zawartości ścieżki.
ChildAdded Pobieraj listy elementów lub słuchaj dodatków do listy elementów. Sugerowane użycie z ChildChanged i ChildRemoved do monitorowania zmian na listach.
ChildChanged Słuchaj zmian w elementach na liście. Używaj z ChildAdded i ChildRemoved , aby monitorować zmiany na listach.
ChildRemoved Posłuchaj, czy elementy są usuwane z listy. Używaj z ChildAdded i ChildChanged do monitorowania zmian na listach.
ChildMoved Słuchaj zmian w kolejności elementów na uporządkowanej liście. Zdarzenia ChildMoved zawsze następują po zdarzeniu ChildChanged , które spowodowało zmianę kolejności elementu (w oparciu o bieżącą metodę zamawiania).

Zdarzenie zmiany wartości

Za pomocą zdarzenia ValueChanged możesz subskrybować zmiany zawartości na danej ścieżce. To zdarzenie jest wyzwalane raz, gdy słuchacz jest podłączony, i ponownie za każdym razem, gdy zmieniają się dane, w tym dzieci. Do wywołania zwrotnego zdarzenia przekazywana jest migawka zawierająca wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócona migawka ma null .

Poniższy przykład ilustruje grę pobierającą wyniki tabeli lideró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 DataSnapshot , który zawiera dane w określonej lokalizacji w bazie danych w momencie wystąpienia zdarzenia. Wywołanie Value na migawce zwraca Dictionary<string, object> reprezentujący dane. Jeśli w lokalizacji nie ma żadnych danych, wywołanie Value zwraca null .

W tym przykładzie sprawdzany jest również args.DatabaseError , aby sprawdzić, czy odczyt został anulowany. Na przykład odczyt można anulować, jeśli klient nie ma uprawnień do odczytu z lokalizacji bazy danych Firebase. DatabaseError wskaże przyczynę wystąpienia błędu.

Możesz później zrezygnować z subskrypcji wydarzenia, korzystając z dowolnego DatabaseReference , który ma tę samą ścieżkę. Instancje DatabaseReference są efemeryczne i można je traktować jako sposób dostępu do dowolnej ścieżki i zapytania.

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

Wydarzenia dla dzieci

Zdarzenia podrzędne są wywoływane w odpowiedzi na określone operacje wykonywane na elementach podrzędnych węzła w wyniku operacji, takiej jak dodanie nowego elementu podrzędnego za pomocą metody Push() lub aktualizacja elementu podrzędnego za pomocą metody UpdateChildrenAsync() . Każdy z nich razem może być przydatny do nasłuchiwania zmian w określonym węźle w bazie danych. Na przykład gra może używać tych metod łącznie 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 ponownie za każdym razem, gdy do określonej ścieżki dodawane jest nowe dziecko. Do słuchacza przekazywana jest migawka zawierająca dane nowego dziecka.

Zdarzenie ChildChanged jest wywoływane za każdym razem, gdy modyfikuje się węzeł podrzędny. Obejmuje to wszelkie modyfikacje elementów podrzędnych węzła podrzędnego. Zwykle jest używany w połączeniu ze zdarzeniami ChildAdded i ChildRemoved w celu reagowania na zmiany na liście elementów. Migawka przekazana do detektora zdarzeń zawiera zaktualizowane dane elementu podrzędnego.

Zdarzenie ChildRemoved jest wyzwalane w przypadku usunięcia bezpośredniego elementu podrzędnego. Zwykle jest używany w połączeniu z wywołaniami zwrotnymi ChildAdded i ChildChanged . Migawka przekazana do wywołania zwrotnego zdarzenia zawiera dane usuniętego elementu podrzędnego.

Zdarzenie ChildMoved jest wyzwalane za każdym razem, gdy zdarzenie ChildChanged zostanie wywołane przez aktualizację, która powoduje zmianę kolejności elementu podrzędnego. Jest używany 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 także filtrować posortowane wyniki według określonej liczby wyników lub zakresu kluczy lub wartości.

Sortuj dane

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

metoda Stosowanie
OrderByChild() Uporządkuj wyniki według wartości określonego klucza podrzędnego.
OrderByKey() Uporządkuj wyniki według kluczy podrzędnych.
OrderByValue() Uporządkuj wyniki według wartości podrzędnych.

Można używać tylko jednej metody zamawiania na raz. Wielokrotne wywołanie metody sortowania według tego samego zapytania powoduje błąd.

Poniższy przykład ilustruje, jak można 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 odbiornikiem zdarzeń o zmianie wartości synchronizuje klienta z tabelą liderów w bazie danych, uporządkowaną według wyniku każdego wpisu. Więcej informacji na temat efektywnego strukturyzacji danych można znaleźć w artykule Struktura bazy danych .

Wywołanie metody OrderByChild() określa klucz podrzędny, według którego mają zostać uporządkowane wyniki. W tym przypadku wyniki są sortowane według wartości "score" u każdego dziecka. Więcej informacji na temat porządkowania innych typów danych można znaleźć w artykule Jak uporządkowane są dane zapytań .

Filtrowanie danych

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

metoda Stosowanie
LimitToFirst() Ustawia maksymalną liczbę elementów do zwrócenia od początku uporządkowanej listy wyników.
LimitToLast() Ustawia maksymalną liczbę elementów zwracanych z końca uporządkowanej listy wyników.
StartAt() Zwracaj elementy większe lub równe określonemu kluczowi lub wartości, w zależności od wybranej metody sortowania.
EndAt() Zwróć produkty mniejsze lub równe określonemu kluczowi lub wartości, w zależności od wybranej metody zamawiania.
EqualTo() Zwróć pozycje równe określonemu kluczowi lub wartości, w zależności od wybranej metody sortowania.

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

Nawet jeśli zapytanie odpowiada tylko jednemu dopasowaniu, zrzut ekranu nadal jest listą; zawiera tylko jeden element.

Ogranicz liczbę wyników

Możesz użyć metod LimitToFirst() i LimitToLast() , aby ustawić maksymalną liczbę dzieci, które mają być synchronizowane dla danego wywołania zwrotnego. Na przykład, jeśli użyjesz LimitToFirst() do ustawienia limitu na 100, początkowo otrzymasz tylko do 100 wywołań zwrotnych ChildAdded . Jeśli w bazie danych Firebase przechowywanych jest mniej niż 100 elementów, dla każdego elementu uruchamiane jest wywołanie zwrotne ChildAdded .

Gdy elementy się zmieniają, otrzymujesz wywołania zwrotne ChildAdded dla elementów, które wchodzą do zapytania, oraz wywołania zwrotne ChildRemoved dla elementów, które z niego wypadają, tak że łączna liczba pozostaje na poziomie 100.

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

Filtruj według klucza lub wartości

Za pomocą funkcji StartAt() , EndAt() i EqualTo() można wybrać 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, które mają określoną wartość.

Sposób uporządkowania danych zapytania

W tej sekcji wyjaśniono, w jaki sposób dane są sortowane według każdej metody porządkowania w klasie Query .

OrderByChild

W przypadku korzystania z OrderByChild() dane zawierające określony klucz podrzędny są porządkowane w następujący sposób:

  1. Dzieci z wartością null dla określonego klucza podrzędnego są traktowane jako pierwsze.
  2. Następne są dzieci 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ępne są dzieci 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ępne są dzieci z wartością liczbową, posortowane w kolejności rosnącej. Jeśli wiele 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ą umieszczane na końcu i są sortowane leksykograficznie według kluczy w kolejności rosnącej.

OrderByKey

Podczas sortowania danych za pomocą OrderByKey() dane są zwracane w kolejności rosnącej według klucza.

  1. Na pierwszym miejscu znajdują się dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, posortowane w kolejności rosnącej.
  2. Następne są dzieci, których kluczem jest wartość ciągu, posortowane leksykograficznie w kolejności rosnącej.

OrderByValue

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