Pobieranie danych

W tym dokumencie opisano podstawy pobierania danych oraz sposób 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 zestaw Firebase Unity SDK (konkretnie 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 odwołaniu do FirebaseDatabase . Odbiornik zdarzeń jest wywoływany raz dla początkowego stanu danych i ponownie za każdym razem, gdy dane się zmieniają.

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

Odczytaj dane raz

Możesz użyć metody GetValueAsync , aby raz 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 jest 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 w danych:

Wydarzenie	Typowe użycie
ValueChanged	Odczytywanie i nasłuchiwanie 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 pozycji na liście. Użyj z ChildAdded i ChildRemoved , aby monitorować zmiany na listach.
ChildRemoved	Słuchaj, czy elementy są usuwane z listy. Użyj z ChildAdded i ChildChanged , aby monitorować zmiany na listach.
ChildMoved	Słuchaj zmian 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 (na podstawie bieżącej metody zamawiania według).

Zdarzenie ValueChanged

Możesz użyć zdarzenia ValueChanged , aby subskrybować zmiany zawartości w danej ścieżce. To zdarzenie jest wyzwalane raz, gdy odbiornik jest podłączony, i ponownie za każdym razem, gdy zmieniają się dane, w tym elementy podrzędne. Wywołanie zwrotne zdarzenia przekazuje migawkę zawierającą wszystkie dane w tej lokalizacji, w tym dane podrzędne. Jeśli nie ma danych, zwrócona migawka jest 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 czasie 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 args.DatabaseError jest również sprawdzane, 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, dlaczego wystąpił błąd.

Możesz później anulować subskrypcję zdarzenia przy użyciu dowolnego DatabaseReference , który ma tę samą ścieżkę. Instancje DatabaseReference są efemeryczne i można je traktować jako sposób uzyskiwania dostępu do dowolnej ścieżki i zapytania.

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

Wydarzenia dla dzieci

Zdarzenia podrzędne są wyzwalane w odpowiedzi na określone operacje, które mają miejsce na elementach podrzędnych węzła z operacji, takich jak dodanie nowego elementu podrzędnego za pomocą metody Push() lub zaktualizowanie elementu podrzędnego za pomocą metody UpdateChildrenAsync() . Każde z nich razem może być przydatne do nasłuchiwania zmian w określonym 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 w bazie danych Firebase. Zdarzenie ChildAdded jest zgłaszane raz dla każdego istniejącego elementu podrzędnego, a następnie ponownie za każdym razem, gdy do określonej ścieżki zostanie dodany nowy element podrzędny. Odbiornik otrzymuje migawkę zawierającą dane nowego dziecka.

Zdarzenie ChildChanged jest zgłaszane za każdym razem, gdy zostanie zmodyfikowany węzeł podrzędny. Obejmuje to wszelkie modyfikacje potomków 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 po usunięciu 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 jest zgłaszane 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 Query do bazy danych czasu rzeczywistego, aby pobrać dane posortowane według klucza, wartości lub wartości elementu podrzędnego. Możesz także filtrować posortowany wynik do 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 w celu określenia kolejności wyników:

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

W danym momencie możesz użyć tylko jednej metody zamawiania według. Wielokrotne wywołanie metody sortowania według w tym samym zapytaniu spowoduje zgłoszenie błędu.

Poniższy przykład pokazuje, 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 detektorem zdarzeń ze zmienioną wartością synchronizuje klienta z rankingiem w bazie danych, uporządkowanym według wyniku każdego wpisu. Więcej informacji na temat efektywnego organizowania 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 takim przypadku wyniki są sortowane według wartości "score" w każdym dziecku. Aby uzyskać więcej informacji na temat porządkowania innych typów danych, zobacz Jak uporządkowane są dane zapytania .

Filtrowanie danych

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

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 do zwrócenia z końca uporządkowanej listy wyników.
StartAt()	Zwróć elementy większe lub równe podanemu kluczowi lub wartości w zależności od wybranej metody zamawiania.
EndAt()	Zwracaj przedmioty mniejsze lub równe podanemu kluczowi lub wartości, w zależności od wybranej metody zamawiania.
EqualTo()	Zwróć elementy równe określonemu kluczowi lub wartości w zależności od wybranej metody zamawiania.

W przeciwieństwie do metod sortowania według, 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 istnieje tylko jedno dopasowanie do zapytania, migawka nadal jest listą; zawiera tylko jeden element.

Ogranicz liczbę wyników

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

Gdy elementy się zmieniają, otrzymujesz wywołania zwrotne ChildAdded dla elementów, które wprowadzają zapytanie, 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 najwyższy wynik z tablicy 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

StartAt() , EndAt() i EqualTo() można używać do wybierania dowolnych punktów początkowych, końcowych i równoważnych 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ść.

Jak uporządkowane są dane zapytania

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

OrderByChild

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

1. Dzieci z wartością null dla określonego klucza podrzędnego są na pierwszym miejscu.
2. Dzieci z wartością false dla określonego klucza potomnego są następne. Jeśli wiele elementów podrzędnych ma wartość false , są one sortowane leksykograficznie według klucza.
3. Dzieci z wartością true dla określonego klucza podrzędnego są następne. 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 rosnąco. 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 występują po liczbach i są sortowane leksykograficznie w porządku rosnącym. 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 porządku rosnącym.

OrderByKey

Gdy używasz OrderByKey() do sortowania danych, dane są zwracane w porządku rosnącym według klucza.

1. Dzieci z kluczem, który można przeanalizować jako 32-bitową liczbę całkowitą, są pierwsze, posortowane w porządku rosnącym.
2. Dzieci z wartością ciągu jako kluczem są następne, posortowane leksykograficznie w porządku rosnącym.

OrderByValue

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